Docs

OIDC settings for apps

# OIDC settings for apps

You can find the OpenID Connect protocol related settings under protocol section of the selected application. OIDC settings

# Basic settings

# Client credentials

When your application is registered in Asgardeo, a client ID is generated as the identifier of the application. If you register a traditional web application, a client secret is generated in addition to the client ID as shown below.

Get client ID and secret of webapp

# Allowed grant types

This will determine how the application communicates with the token service. Web application template supports following grant types:

Grant type Description
Code Used for executing the OAuth2 Authorization Code flow in client applications. Upon user authentication, the client receives an authorization code, which is then exchanged for an access token. The client can use this token to access the required resources.
Client Credentials Used for executing the OAuth2 Client Credentials flow in client applications. Users are authenticated from the user credentials and an access token is granted. The client can use this token to access the required resources.
Refresh Token The client can use the refresh token to get a new access token when the original access token expires, without having the user re-authenticate.
Implicit Used for executing the OAuth2 Implicit flow in client applications. Clients without a back-channel (hence cannot securely store secrets) can receive the access token directly in the URL. This grant type is not recommended.
Password Used for executing the OAuth2 Password flow in client applications. The client sends the user's credentials to get an access token. This grant type is not recommended.
Organization Switch A custom OAuth2 grant type that allows clients to get access to organization APIs in Asgardeo. The client can exchange the access token received from the root organization for an access token of the organization.

It is recommended to use code grant for public clients. For single-page application templates, code grant is enabled by default. You can enable refresh token grant to get refresh tokens. However, implicit grant (opens new window) and password (opens new window) grants are not recommended due to security reasons.

See grant types of Asgardeo for more details.

# Public client

A public client is an application which cannot keep the client credentials in secure way. It is recommended to use authorization code grant type for public clients. In addition to that, PKCE (opens new window) should be used along with authorization code to mitigate code interception attacks. A public client does not need to authenticate to Asgardeo with client_secret.

# Authorized redirect URLs

Authorized redirect URLs are not required for Client Credentials and Password grant type.

Authorized redirect URLs determine where Asgardeo will redirect users after authentication and logout. An application can have multiple Authorized redirect URLs.

The redirect_uri sent in the login request and the post_logout_redirect_uri sent in the logout request should match with one of the registered authorized redirect URLs.

# Allowed origins

For security reasons, browsers restrict cross-origin HTTP requests initiated from browser scripts. Cross Origin Resource Sharing(CORS) (opens new window) allows your application to do cross-origin HTTP requests.

Allowed origins are the set of URLs that are allowed to access Asgardeo APIs from javascript. By pre-registering the application origin as an allowed one, applications can access APIs of Asgardeo:

  • Token endpoint
  • JWKS endpoint
  • Userinfo endpoint
  • Other APIs

# Advanced settings

# Proof Key for Code Exchange(PKCE)

# Mandatory

By enabling this option, Asgardeo mandates an application to use PKCE (opens new window) with the authorization code flow. The application has to send a code challenge in the authorization request and the corresponding code verifier in the token request. Asgardeo supports SHA-256 and plain.

Sample authorization request

https://api.asgardeo.io/t/bifrost/oauth2/authorize?scope=openid&response_type=code&redirect_uri=<redirect_uri>&client_id=<client_id>&code_challenge=<code_challenge>&code_challenge_method=<code_challenge_method>
1

Sample token request:

# Support Plain Transform Algorithm

If this configuration is selected, the applications can use plain algorithm. i.e,code_challenge = code_verifier. But this is not recommended due to security best practises.

https://api.asgardeo.io/t/bifrost/oauth2/authorize?response_type=code&client_id=Wsoq8t4nHW80gSnPfyDvRbiC__Ea&scope=openidprofile&redirect_uri=http%3A%2F%2Flocalhost%3A5000&code_challenge_method=plain&code_challenge=nAkA5m0EKlFbHFvF_V53Icig9gSnqr-HxH44Lvkne2c
1

Sample token request:

# Access Token

# Token type

In additional to usual opaque tokens, Asgardeo supports self-contained JWT tokens as well.

  1. Opaque: These types of tokens are plain text tokens. If a resource server wants to know information related to opaque token, it has to query introspection endpoint and get the information related to tokens.
{
"access_token": "9fac7747-bb2d-46be-bef2-a95b2f69f8b2",
"scope": "openid",
"id_token": "eyJ4NXQiOiJZemM1T1Rnd1pURTNNV1F6TVdFek5ERm1OelZoTTJOaU9UQmxOamN3TlRJNU9HTTBNbVExWWprd1lqZzJNVEl3WldNd056TTRNemcxWkdJeVpEZzNaQSIsImtpZCI6Ill6YzVPVGd3WlRFM01XUXpNV0V6TkRGbU56VmhNMk5pT1RCbE5qY3dOVEk1T0dNME1tUTFZamt3WWpnMk1USXdaV013TnpNNE16ZzFaR0l5WkRnM1pBX1JTMjU2IiwiYWxnIjoiUlMyNTYifQ.eyJpc2siOiJhYjdlMDNlMGQ3MzlkNmVlNmQxYTJkMGYwMTk0NDJiZDJiMDE5MDQyNjhiYzY5ZTkyYTg3OTViMjViYmU1NTdkIiwiYXRfaGFzaCI6IkNYb2hyLU9kZ1pISTF6VElvNHF6cmciLCJhdWQiOiJXc29xOHQ0bkhXODBnU25QZnlEdlJiaUNfX0VhIiwiY19oYXNoIjoiajBhd1lkTGtOVF9mdVBzNVcwZ2VFUSIsInN1YiI6IkFsaWNhQGJpZnJvc3QuY29tIiwibmJmIjoxNjIzOTA0ODgzLCJhenAiOiJXc29xOHQ0bkhXODBnU25QZnlEdlJiaUNfX0VhIiwiYW1yIjpbIkJhc2ljQXV0aGVudGljYXRvciJdLCJpc3MiOiJodHRwczpcL1wvYWNjb3VudHMuYXNnYXJkZW8uaW9cL3RcL2JpZnJvc3RcL29hdXRoMlwvdG9rZW4iLCJleHAiOjE2MjM5MDg0ODMsImlhdCI6MTYyMzkwNDg4M30.XHNsUSAcaRAFvOmWB366fdhbQzQxsDiJC0ADD1kiWpiFentvl6fh3h1ITN-x92623cJDYZbC-YK_OdeZ3X7hYLHOK6UXu_gEA4GIaExl7B3iWB9XLukdbU67AX-QpqPFbPgYLqq3CIyyYUxjDC9F22CQreWREc8neLkMW0ejMvZSK7q3hNtuxh6Ox2yhoIJT4KgCygZO259L8xzp6ZuCNDp39nIRsj4zjTOuvz92Md6DC_eauS1BF0SaIZO4YG1PW-FVfmOppcqE0P3MCH8D3EOvmSj2ZqSJRy5hki8E7LOmBhUp4O6yLPWEgFf8QGNa2xAIWK2YqX4kezEyj6Iftw",
"token_type": "Bearer",
"expires_in": 3522
}
1
2
3
4
5
6
7
  1. JWT token: JWT tokens are self-contained verifiable access tokens. They contain information related to tokens. If a resource server wants to know the information related to that token, it can decode the token and get the required information without any additional network calls.
{
 "access_token": "eyJ4NXQiOiJZemM1T1Rnd1pURTNNV1F6TVdFek5ERm1OelZoTTJOaU9UQmxOamN3TlRJNU9HTTBNbVExWWprd1lqZzJNVEl3WldNd056TTRNemcxWkdJeVpEZzNaQSIsImtpZCI6Ill6YzVPVGd3WlRFM01XUXpNV0V6TkRGbU56VmhNMk5pT1RCbE5qY3dOVEk1T0dNME1tUTFZamt3WWpnMk1USXdaV013TnpNNE16ZzFaR0l5WkRnM1pBX1JTMjU2IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJBbGljYUBiaWZyb3N0LmNvbSIsImF1dCI6IkFQUExJQ0FUSU9OX1VTRVIiLCJhdWQiOiJXc29xOHQ0bkhXODBnU25QZnlEdlJiaUNfX0VhIiwibmJmIjoxNjIzOTA0ODA1LCJhenAiOiJXc29xOHQ0bkhXODBnU25QZnlEdlJiaUNfX0VhIiwic2NvcGUiOiJvcGVuaWQiLCJpc3MiOiJodHRwczpcL1wvYWNjb3VudHMuYXNnYXJkZW8uaW9cL3RcL2JpZnJvc3RcL29hdXRoMlwvdG9rZW4iLCJleHAiOjE2MjM5MDg0MDUsImlhdCI6MTYyMzkwNDgwNSwianRpIjoiOWZhYzc3NDctYmIyZC00NmJlLWJlZjItYTk1YjJmNjlmOGIyIn0.ETimDfsoXiV2wqkCy7ZWZ-cO3mK8VaGKXvbBeFd8hh5TceGppRvrOs_0Kxez6p8gVRTrCbv-iBIrJFikl_I_euqTk30-JfPxvh0ox5RxY_4nsXs8GGycJwL40XfssE5BLlFSff2YIsbvy6Mbih8_Jerb-RA6j7cAZSII_T-4ATD7mk9DeXmK_-jwqBoyH0UNtAxJKLgfIs8G2yIiioaS4rSnX8tEGGvPvcaDzeTdNx2RNKod_EYlWDNJVtJHUf61lstu4WSA0pdHyP5_Fpbhe4pu_FaXeSMyAwsHYIENWVarB8kknvyUnL51lkoOrIJaSHRjqIbSNteIJ3QyEQ-a8Q",
 "scope": "openid",
 "id_token": "eyJ4NXQiOiJZemM1T1Rnd1pURTNNV1F6TVdFek5ERm1OelZoTTJOaU9UQmxOamN3TlRJNU9HTTBNbVExWWprd1lqZzJNVEl3WldNd056TTRNemcxWkdJeVpEZzNaQSIsImtpZCI6Ill6YzVPVGd3WlRFM01XUXpNV0V6TkRGbU56VmhNMk5pT1RCbE5qY3dOVEk1T0dNME1tUTFZamt3WWpnMk1USXdaV013TnpNNE16ZzFaR0l5WkRnM1pBX1JTMjU2IiwiYWxnIjoiUlMyNTYifQ.eyJpc2siOiJhYjdlMDNlMGQ3MzlkNmVlNmQxYTJkMGYwMTk0NDJiZDJiMDE5MDQyNjhiYzY5ZTkyYTg3OTViMjViYmU1NTdkIiwiYXRfaGFzaCI6IjZSWkQ4a2lZYkFpZkh4OENldWJUcXciLCJhdWQiOiJXc29xOHQ0bkhXODBnU25QZnlEdlJiaUNfX0VhIiwiY19oYXNoIjoiWjVPXzk5cmZFSkFabjJSUl9yTEhxZyIsInN1YiI6IkFsaWNhQGJpZnJvc3QuY29tIiwibmJmIjoxNjIzOTA0ODA1LCJhenAiOiJXc29xOHQ0bkhXODBnU25QZnlEdlJiaUNfX0VhIiwiYW1yIjpbIkJhc2ljQXV0aGVudGljYXRvciJdLCJpc3MiOiJodHRwczpcL1wvYWNjb3VudHMuYXNnYXJkZW8uaW9cL3RcL2JpZnJvc3RcL29hdXRoMlwvdG9rZW4iLCJleHAiOjE2MjM5MDg0MDUsImlhdCI6MTYyMzkwNDgwNSwic2lkIjoiOTE3MzQzOGQtNDFlNy00MmFhLWFmZTctNjlkNDM3Njk1NTRlIn0.f9rTgJtDD6VAUQ1fXZCbiUtg66B0Q5nNSgGTIbrCI6aBC8sn2QmhI4YFqXntj72b2T7-TTYXiY4k6iQH665Oc_KfhxJIwrCW4X96h6dMMHcDMQYuP5blZNMuP8fi42sFAVgAUcs4B5Lfq-nIiPrqO90XGJVyrzJEdSoGsgbX9fg6HWbx016Shla2oKeVzsvZra6uflk4S1bsEVnk5gmRjZ25Vueqtb5qJW291i38-dKhO6FDEkAJyw_QWG6nK_ZpOMx4GW6qj0GTEKrC_TuUTp5hUX1xUnpLRFHcN8WAQoe7_g6JyLOUQzQSFTr-CniwwftwnK0DcGq916bRPvTEjw",
 "token_type": "Bearer",
 "expires_in": 3600
}
1
2
3
4
5
6
7

# User access token expiry time

This provides the validity period of access tokens issued to a user in seconds. The default expiry time is 3600 seconds.

# Application access token expiry time

This specifies the validity period of the access tokens issued to an application with the Client Credentials grant in seconds.

# Token binding type

Token binding securely links authentication tokens to client devices to prevent unauthorized token theft and replay attacks. It is a vital mechanism, especially when dealing with unsecured networks, as it provides an additional layer of security against unauthorized access.

Asgardeo offers the following token binding types.

Binding type Description
none Does not establish any specific binding between the token and the client device. Suitable for scenarios where token binding is not required or implemented separately. This is the default token binding type of any application.
cookie Binds the token to a cookie named atbv with Secure and httpOnly parameters. Supported with the authorization_code grant type. Validate Token Binding can be enabled to mandate client sends both the token and the cookie for successful authorization.
sso-session Binds the token to the browser session. During each login, a token is generated coupled to the browser session and revoked on user logout. Supported with the authorization_code grant type.
client-request Binds the token to the instance identifier as requested by the client through the tokenBindingId parameter with the token request as shown below.

curl -X POST
-u "<client_id>:<client_secret>" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&username=<user_name>&password=<user_password>&tokenBindingId=<your_unique_token_binding_id>" https://api.asgardeo.io/t/<organization_name>/oauth2/token

Generally for applications that involve multiple instances and use back-channel grant types such as token exchange or password.

# ID Token

# Audience

Specifies the recipient(s) that this ID token is intended for. By default, the client ID of this application is added as an audience. You can add multiple audiences in the ID token.

Sample default ID token:

{
 "isk": "c37e33a87f794f9db4e43eeec5596dd0f64ba43c2c8a6e35eb4bd09e8a09d58a",
 "at_hash": "sXH3BGop66MmXp0CCWDk2A",
 "aud": "Wsoq8t4nHW80gSnPfyDvRbiC__Ea",
 "c_hash": "IgFIyrsoOeTwjdAaG3y3OQ",
 "sub": "[email protected]",
 "nbf": 1623843889,
 "azp": "Wsoq8t4nHW80gSnPfyDvRbiC__Ea",
 "amr": [
   "BasicAuthenticator"
 ],
 "iss": "https://api.asgardeo.io/t/bifrost/oauth2/token",
 "exp": 1623847489,
 "iat": 1623843889
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Sample ID token when sample_app is added as a audience value:

{
 "isk": "1f77c2907c1c2670d73909d3dad38cd02ecda3c21a343dec9d75b51630ca5418",
 "at_hash": "a387Ursh5iNxeMmNViWT2A",
 "aud": [
   "Wsoq8t4nHW80gSnPfyDvRbiC__Ea",
   "sample_app"
 ],
 "c_hash": "tz02tie7nYsK4__SFj2uKQ",
 "sub": "[email protected]",
 "nbf": 1623908834,
 "azp": "Wsoq8t4nHW80gSnPfyDvRbiC__Ea",
 "amr": [
   "BasicAuthenticator"
 ],
 "iss": "https://api.asgardeo.io/t/bifrost/oauth2/token",
 "exp": 1623912434,
 "iat": 1623908834
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# Enable encryption

Specifies whether to enable encryption for the ID token when the token is issued. The public key of your application is used for encryption.

To enable encryption, you should configure the certificate of your application from the Certificates section.

# Algorithm

A single-use AES secret key, called the Content Encryption Key (CEK), is generated to encrypt the ID token payload.

Asgardeo uses the public Key of the application (obtained from the certificate) and the asymmetric encryption algorithm specified here to encrypt the generated CEK. The selected algorithm is mentioned as the "alg" in the ID token header.

# Encryption Method

The encryption method defines a symmetric encryption algorithm for encrypting ID tokens.

Asgardeo uses a generated CEK value and the symmetric encryption algorithm specified here to encrypt the ID token. The selected encryption method is mentioned as the "enc" in the id token header.

# ID Token expiry time

Provides the validity period of ID token in seconds. The default value is 3600 seconds.

# Refresh Token

These configurations are enabled only if refresh token grant type is added as an allowed grant type.

# Renew refresh token

Asgardeo issues a new refresh token each time when access token is refreshed with refresh token grant type. The previous token gets invalidated.

If the application does not want to get a new refresh token for each request, you can clear the Renew refresh token checkbox. Then, the same refresh token will be issued with refresh token grant type until the refresh token expires.


# Refresh token expiry time

Provides the validity period of refresh token in seconds. The default value is 86400 seconds.

# Certificate

The certificate is used to validate signatures of signed requests from the application to Asgardeo and to encrypt requests from Asgardeo to the application.

You can either Provide Certificate or Use JWKS endpoint to add a certificate.
Follow the steps given below to Provide Certificate.

  1. Select Provide Certificate and click New Certificate. Upload app certificate

  2. Upload the certificate file or copy the certificate contents.

If you have a certificate in other formats such as .crt, .cer or .der, convert it to the PEM format using OpenSSL

Convert CRT to PEM

openssl x509 -in cert.crt -out cert.pem
1

Convert CER to PEM:

openssl x509 -in cert.cer -out cert.pem
1

Convert DER to PEM:

openssl x509 -in cert.der -out cert.pem
1

© 2024 WSO2 LLC.