Configure OAuth or OpenID Connect for custom applications

ADSelfService Plus supports SSO logins to any OAuth or OpenID Connect-enabled custom enterprise application. In this document, get the steps to configure OpenID Connect-based SSO for custom applications.

Steps to create a custom application in ADSelfService Plus

Prerequisite

1. Log in to the service provider (SP) using administrator credentials. The SP is the custom application for which you want to configure OpenID Connect.
2. Copy the Authorization redirect or callback URL(s) from the SP.

Configuration steps

1. Log in to ADSelfService Plus using administrator credentials.
2. Navigate to Configuration > Self-Service > Password Sync/Single Sign On.
3. Click Add Application.
4. Click the Custom Application option in the left pane.
5. Enter a suitable Name and Description for the application.
6. Enter the Domain Name for your application account. For example, if your username is johndoe@thinktodaytech.com, then thinktodaytech.com is your domain name.
7. Choose the policies you want to assign from the Assign Policies drop-down.
8. You can also add a small or large icon of the application, if desired.
9. Under the SSO tab, select Enable Single Sign-On.
10. From the Select Sign-on Method drop-down, choose OAuth/OpenID Connect.
11. From the Supported SSO Flow drop-down, choose SP-Initiated or IdP-Initiated.
Note: It is advisable to contact the support team of your SP application and verify the supported SSO flow(s) before choosing the supported SSO flow.

If selecting SP-Initiated flow



1. Enter the URL of the service provider's login page in the SP Login Initiate URL field.
Note: Some apps require sign-in to begin from their login page, known as SP-initiated login. Users are first directed to the app's login page, specified in the SP Login Initiate URL field, after which the SP redirects them to ADSelfService Plus, the identity provider (IdP) for authentication.

If selecting IdP-Initiated flow



1. Enter the application portal's login URL in the IdP Login Initiate URL field.
Note: The IdP Login Initiate URL is used to send the id_token from the IdP to the SP. Once this URL is configured, users will be able to log in to the SP by clicking that particular application in the ADSelfService Plus user portal.
12. In the Login Redirect URL(s) field, enter all the available Authorization redirect or callback URLs obtained from your SP in step 2 of the prerequisites. The URL(s) can be found in the SP's OAuth/OIDC SSO configuration page.
13. Under Response Type, choose one or more options: Authorization code, Access Token, and ID Token.



Note: This value will be reflected in the Well-known configuration section under IdP details, and shared to the SP application. Response Type is used to reference the authorization request modes from SP to IdP. This can be chosen based on the SP's login requirement.
• Authorization Code: Using this response type, the IdP sends an authorization code to the SP after a successful authorization request. With this authorization code, the SP then sends an access token request to the IdP. Using this access token, the SP obtains user information to perform the user login.
• Access Token: Using this response type, the IdP sends an access token to the SP after a successful authorization request. Using this access token, the SP obtains user information to perform the user login.
• ID Token: Using this response type, the IdP sends an ID token to the SP after a successful authorization request. Using this ID token, the SP obtains user information to perform the user login.
14. Click the Allow Refresh Token check box to allow the SP to obtain access tokens without needing the user to re-authenticate every time.
15. The Access Token Validity field is set to 3600 seconds by default. You can change this value if required.
Note: Access Token Validity denotes the time limit for which the token sent by the IdP will be accessible by the SP.
16. From the Key Algorithm drop-down, choose the appropriate algorithm: HS256, RS256, RS384, or RS512.
Note: The Key Algorithm is the algorithm used to sign tokens, such as the id_token or access_token. Using an algorithm to sign tokens ensures the token's integrity and authenticity.



HS256: A symmetric algorithm that uses one shared secret (i.e. client_secret generated during custom application creation in IdP), to sign and validate the token instead of using a public key pair.

RS256: RSA signature with SHA-256. It is an asymmetric algorithm which uses a public or private key pair, generated and managed by IdP (the IdP uses the private key to generate the signature, and the application uses a public key to validate the signature).

RS384: Same as RS256, except this uses a SHA-384 hashing algorithm for creating the RSA signature.

RS512: Same as RS256, except this uses a SHA-512 hashing algorithm for creating the RSA signature.
17. From the Client Authentication Mode drop-down, choose the modes required. These are the modes by which the IdP will authenticate the SP's access token request.



Client Secret Basic: The IdP generates a client_id and and shares it with the SP in advance. While sending access token request, the SP encodes the client_id and client_secret in BASE64 and sets it in the authorization header. The IdP verifies this authorization header to authorize the request.

Client Secret Post: The IdP generates a client_id and client_secret and shares it with the SP in advance. While sending access token request, the SP sets the client_id and client_secret in the access token request body. The IdP verifies the client_id and client_secret in the request body to authorize the request.

PKCE Code Challenge: The SP generates a random value called code_verifier, which is hashed to form a code_challenge. While sending access token request, the SP sends this code_challenge to the IdP. The IdP checks this code_challenge to authorize the request.

Client Secret JWT: The IdP generates a client_secret_jwt and shares it with the SP in advance. While sending access token request, the SP, uses this secret to generate a digital signature. The IdP checks for the signature to authorize the request.

Private Key JWT: The IdP gets a JWKS URL (i.e., JSON web key set) from the SP that consists of a public key. While sending access token request, the SP uses a private key to generate a digital signature. The IdP checks for the signature using the public key obtained from JWKS URL to authorize the request.
18. On choosing the Private Key JWT mode, ADSelfService Plus will need the JWKS URL details from the SP to obtain the public key, which will then be used to verify the signature.



19. Click Advanced Configuration in the top-right corner.
20. Under OAuth/OpenID Connect Claim Attributes Configuration, map the attributes as given in the screenshot below.



21. Click Create Custom Application.

The users who fall under the policies you chose in step 7 can now sign into the custom application from their user portal using SSO.