The Single Sign-On browser flow is used to authenticate users and grant access to their protected resources in Kapital Bank. However, if Birbank continues continues with mobile flow. To forward the user to our SSO page, the URL needs to be opened with several request request request request request request request parameters in an HTTP GET request.
SSO is based on OpenID Connect Authorization Code Flow .
Since we are implementing the Code Flow, it is going to be code.
It refers to a permission or access level requested by an application during the authentication process. Scopes define the specific resources or customer information that the application wants to access on behalf of the customer. Scopes should be added to the SSO URL with spaces between them. At the moment, it is necessary to include openid scopes.
It is the name of the client that we set for our partners. So it is going to be your client id.
A login hint is passed by clients to add a login field such as phone number to facilitate the user login process by sending a login field beforehand that is known to the client.
It is a security feature to prevent Cross-Site Request Forgery (CSRF) attacks. It is a random string generated by the client application and added to the request parameters while opening the SSO page. When the user successfully authenticates, this parameter will be returned along with the Authorization Code.
It is used to specify the URL that the authentication server should redirect the user back to after successful authentication. After the user successfully authenticates, the server will redirect the WebView back to the "redirect_uri" specified in the original request, along with the authentication response. The client application can then use the authentication response to complete the user's login process and grant them access to protected resources. In this case, the redirect URI is given as https://client.az/sso_auth for demonstration, and the actual URI should be provided by partners.
It is a parameter used in the OAuth 2.0 Authorization Code Flow with PKCE (Proof Key for Code Exchange) to specify the method used to generate the code challenge. PKCE is a security extension to OAuth 2.0 designed to protect against code injection attacks. When the client application initiates the Authorization Code Flow with PKCE, it generates a code verifier and a code challenge. The code challenge is derived from the code verifier using a specified method (which is S256 in this case).
When the client application generates a random string as a code verifier, it should also calculate its Base64 URL encoded SHA-256 hash to add as code_challenge to the request parameters. Later, when the client calls the token endpoint to get access and refresh tokens for the user, it should add the original code verifier to verify that the token is requested by the authorized party and by not someone who intercepted the request in the middle and obtained the authorization code. Here is a PKCE Tool for testing and development.
Example Authentication Request:
https://dmz.birid.az/auth/ssoValidateUser?response_type=code&client_id=birid-demo&state=b651cf8f2da337b6fd01&code_challenge=A-tNd2HB2vug0r7JZF1j38ruAoW5XiI2u7T_tuzknsc&scope=openid&code_challenge_method=S256&redirect_uri=http://localhost:8080&ui_locales=aztest - https://test.birid.az
pre - https://pre.birid.az
dmz - https://dmz.birid.az
production - https://birid.az
Note : test and pre environments considered for ecosystem partners, dmz is public env for external partners
After successful authentication, the authorization response is redirected to the client application. A sample redirect URI would be:
http://localhost:8080/?state=b651cf8f2da337b6fd01&session_state=9e259049-e618-4cdf-8859-311591f0aa59&code=6397b4a0-5f70-448b-8150-c31001c625bb.9e259049-e618-4cdf-8859-311591f0aa59.22fa4c0d-a75f-47e4-aea6-08cf1ee9274aThere are 3 parameters in the redirect URI:
It is the same input sent in the SSO browser login request. When the client receives the authentication response, it checks whether the returned "state" parameter matches the "state" parameter sent in the original request. If the two "state" parameters match, it means that the response is legitimate and can be trusted. If they do not match, the client application should reject the response. This mechanism helps prevent attackers from impersonating users and tricking them into logging into a different application or performing malicious actions.
This parameter is sent to the client application after the user has completed the OIDC authentication flow. The "session_state" parameter is used to communicate the session identifier to the client application, and the client application can use this parameter to verify that the user's session is still active and has not been tampered with.
To verify the user's session, the application can store the "session_state" parameter in the user's device. Subsequently, when the client application receives a Token Response from the OIDC provider, it can compare the "session_state" parameter in the response to the session state stored in the user's device. If they match, the client application can be sure that the user's session is still active and has not been tampered with. If the "session_state" parameter does not match the stored session state, the client application can assume that the user's session is no longer active and should log the user out.
It is a temporary authorization code that the client application can then use this authorization code to obtain access and refresh tokens by exchanging them for a token through a token endpoint.
The "code" parameter is a one-time-use code that is valid for a short period and can only be used by the client application that originally requested it. This helps to prevent security issues, such as replay attacks and ensures that the authorization code can only be used to obtain a token by the client application that is authorized to do so.
| Description | After obtaining the authorization code, this endpoint is used to retrieve the access and refresh token pair, as well as to perform subsequent token refreshes. |
| HTTP Method | POST |
| URL | /v2/openid-connect/token |
https://dmzid.kapitalbank.az/swagger-ui/index.html
https://dmzid.kapitalbank.az/api
curl -X 'POST' \
'https://dmzid.kapitalbank.az/api/v2/openid-connect/token' \
-H 'accept: */*' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=client&client_secret=secret&code=6b28b7dc-7c8e-407f-a525-233457595815.85d46fc1-4e2e-44d8-8b70-62eea8f2d40c.5cb99e32-fd2c-4f7c-b25b-1b56f10a30f7&redirect_uri=https://client.az/sso_auth&code_verifier=aa1c9b97be0ca6cfdf932bbba36597c4d59cfc19cd54be4e7340c81e'| Name | Type | Mandatory | Description |
|---|---|---|---|
client_id | String | Yes | A string representing the client identifier. This is typically assigned by the authorization server and identifies the client application making the request. |
client_secret | String | Yes | This is a confidential key known only to the client application and the authorization server. It is used to authenticate the client. |
code | String | if grantType is authorization_code | A string representing the authorization code. This code is obtained from the authorization server after the user grants consent to the client application. |
redirect_uri | String | if grantType is authorization_code | This URI is used to redirect the user-agent (usually a web browser) back to the client application after the authorization process is complete. |
code_verifier | String | if grantType is authorization_code | This is used in the PKCE (Proof Key for Code Exchange) extension to OAuth, providing an additional layer of security for the authorization process. |
grant_type | String | Yes | In the context of OAuth 2.0, a grant type is a method used by an application to obtain an access token, with different types such as Authorization Code, Implicit, Resource Owner Password Credentials, and Client Credentials serving different client and resource access scenarios. Each grant type specifies the process for the client to request and receive tokens from the authorization server. Available values: 'authorization_code', 'refresh_token', 'client_credentials' |
refresh_token | String | if grantType is refresh_token | Refresh token for getting new access, id and refresh tokens for existing session. |
| Name | Type | Description |
|---|---|---|
access_token | String | A string representing the access token. This token is typically used by the client application to authenticate itself when making requests to protected resources on behalf of the user. |
expires_in | int64 | A Long value representing the expiration time of the access token in seconds. This provides information about the duration for which the access token is valid. |
refresh_token | String | A string representing the refresh token. The refresh token is used to obtain a new access token without requiring the user to re-authenticate. It is a long-lived credential that can be used to refresh the access token. |
refresh_expires_in | int64 | A Long value representing the expiration time of the refresh token in seconds. Similar to the expires_in field, this indicates the duration for which the refresh token is valid. |
id_token | String | A string representing the ID token. The ID token contains information about the authenticated user and is often used for identity verification. It might include claims such as the user's identity, authentication time, and other user attributes. |
| Description | The logout endpoint invalidates the user’s active session and refresh tokens, ensuring the user cannot access protected resources without re-authentication. |
| HTTP Method | POST |
| URL | /v1/identity/logout |
| Expected Response | HTTP 204 - No Content |
| Name | Format | Description |
|---|---|---|
| Authorization | Bearer ${token} | Bearer access token used to authenticate the user and authorize the logout request. |
curl -X 'POST' \
'https://dmzid.kapitalbank.az/api/v1/identity/logout' \
-H 'accept: */*' \
-H 'Authorization: Bearer ${accessToken}'