OIDC settings for apps

OpenID Connect protocol related settings are under the Protocol section of the application registered in WSO2 Identity Server.

Note

Configurations mentioned in this reference may vary based on the type of application that you register.

Basic settings

The following are the minimum configurations that are required for OIDC applications to run successfully.

Client credentials

When your application is registered in WSO2 Identity Server, a client ID is generated as the identifier of the application. If your application is not a public client, a client secret is generated in addition to the client ID as shown below.

Allowed grant types

This option determines how the application communicates with the token service. Web application template supports the 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 due to security reasons.
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 due to security reasons.
Token Exchange	This is a grant type in the OAuth 2.0 framework that enables the exchange of one type of token for another.
Organization Switch	A custom OAuth2 grant type that allows clients to get access to organization APIs in WSO2 Identity Server. The client can exchange the access token received from the organization (root) for an access token of the organization.

Tip

• It is recommended to use Code grant for public clients.
• For single-page application templates, the Code grant is enabled by default.
• If Code grant is enabled, enable the Refresh Token grant to get refresh tokens.

Note

Learn more about OAuth2 grant types.

Authorized redirect URLs

Authorized redirect URLs determine where WSO2 Identity Server redirects users after login 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 one of the registered authorized redirect URLs.

Note

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

Allowed origins

Browsers restrict cross-origin HTTP requests initiated from browser scripts for security reasons. Enabling Cross Origin Resource Sharing (CORS) allows your application to perform cross-origin HTTP requests.

You should list the set of URLs that are allowed to access WSO2 Identity Server APIs with JavaScript under Allowed origins. By pre-registering the application origin, applications can access:

• the token endpoint
• the JWKS endpoint
• the userinfo endpoint
• other APIs

Advanced settings

This section elaborates on the advanced settings available for OIDC applications on WSO2 Identity Server.

Proof Key for Code Exchange(PKCE)

When using PKCE with authorization code flow, the application sends a code challenge in the authorization request and subsequently, sends the corresponding code verifier in the token request.

PKCE ensures that the authorization code is sent to the same client making the request and no malicious application has intercepted the code during the delivery process. WSO2 Identity Server supports the following options for PKCE:

• Mandatory

  By enabling this option, WSO2 Identity Server makes it mandatory for an application to use PKCE with the authorization code flow grant type. Shown below is a sample request to the /authorize endpoint and the subsequent request to the /token endpoint.

  Sample authorization request

  https://localhost:9443/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>
  

  Sample token request

  cURLJavaScript - jQueryNodejs - Axios

  curl --location --request POST 'https://localhost:9443/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'code=60cb4ba7-b7b2-3f2f-8319-58122f1b2f5d' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'redirect_uri=https://localhost:5000' \
  --data-urlencode    'code_verifier=WAOqjmxMpCnjME0mRpd8pDZNT8bEIpCdHgMKFqxoAVtEb4LhJ0KSg8Rl0z0O3pySx4HGp53R87bckxOxrXk2oNav0fgWzFdOy  BR rvA8ZTgCG7MlQcY9mfamCM8SWnGgO' \
  --data-urlencode 'client_id=fv_LScHaB83PN4VPX1cHufphtHQa'
  

  var settings = {
      "url": "https://localhost:9443/oauth2/token",
      "method": "POST",
      "timeout": 0,
      "headers": {
          "Content-Type": "application/x-www-form-urlencoded"
      },
      "data": {
          "code": "60cb4ba7-b7b2-3f2f-8319-58122f1b2f5d",
          "grant_type": "authorization_code",
          "redirect_uri": "https://localhost:5000",
          "code_verifier":    "WAOqjmxMpCnjME0mRpd8pDZNT8bEIpCdHgMKFqxoAVtEb4LhJ0KSg8Rl0z0O3pySx4HGp53R87bckxOxrXk2oNav0fgWzFdOyBRrvA8  ZT gCG7MlQcY9mfamCM8SWnGgO",
          "client_id": "fv_LScHaB83PN4VPX1cHufphtHQa"
      }
  };
  
  $.ajax(settings).done(function (response) {
      console.log(response);
  });
  

  var axios = require('axios');
  var qs = require('qs');
  var data = qs.stringify({
      'code': '60cb4ba7-b7b2-3f2f-8319-58122f1b2f5d',
      'grant_type': 'authorization_code',
      'redirect_uri': 'https://localhost:5000',
      'code_verifier':    'WAOqjmxMpCnjME0mRpd8pDZNT8bEIpCdHgMKFqxoAVtEb4LhJ0KSg8Rl0z0O3pySx4HGp53R87bckxOxrXk2oNav0fgWzFdOyBRrvA8ZTgC  G7 MlQcY9mfamCM8SWnGgO',
      'client_id': 'fv_LScHaB83PN4VPX1cHufphtHQa'
  });
  var config = {
      method: 'post',
      url: 'https://localhost:9443/oauth2/token',
      headers: {
          'Content-Type': 'application/x-www-form-urlencoded'
      },
      data: data
  };
  
  axios(config)
      .then(function (response) {
          console.log(JSON.stringify(response.data));
      })
      .catch(function (error) {
          console.log(error);
      });
  

• Support Plain Transform Algorithm

  If this configuration is selected, the applications can use the plain algorithm. i.e,code_challenge = code_verifier. As the code_verifier is visible to a malicious party, this is not recommended for production environments.

  https://localhost:9443/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
  

Client authentication

For applications that rely on a client secret, client authentication method is the mechanism used to verify the identity of the client application when requesting for an access token. The following are the available client authentication methods in WSO2 Identity Server.

Client authentication method	Description
Client Secret Basic	Client applications use HTTP basic authentication to authenticate with the authorization server. The client secret is included in the authorization header as a base 64 encoded string as shown below. Authorization: Basic base64(client_id:client_secret)
Client Secret Post	The client application sends the client secret in the body of the HTTP POST request when requesting an access token.
Mutual TLS	Client authentication happens with TLS certificates. The server and the client both present their certificates to each other during the TLS handshake and establish a two-way trust relationship. When configuring, enter the domain name of the client certificate under TLS client authentication subject domain name.
Private Key JWT	Client authentication happens with a public/private key pair. The client sends a client assertion, a client-generated JSON Web Token (JWT), signed with the private key. The authorization server will verify the assertion with the client's public key. When configuring, enter the required signing algorithm.

Public client

A public client is an application which cannot securely store client credentials. A public client does not need to authenticate with a client_secret. Thus to secure public clients, it is recommended to use Code grant type for public clients along with PKCE to mitigate code interception attacks.

Pushed Authorization Requests (PAR)

When an application initiates an authorization request with Pushed Authorization Reqeusts (PAR), it sends the payload to the /par endpoint from the back channel, and includes a reference to the payload in the authorization request.

Selecting the Mandatory option enforces the application to initiate an authorization request with PAR.

Note

Learn more about Pushed Authorization Requests.

Request Object

OAuth 2.0 authorization requests can either include the authorization parameters in URL query strings or in a request object. A request object is typically a JSON Web Token (JWT) which encapsulates the authorization parameters. It can be signed and encrypted to respectively ensure data integrity and data confidentiality.

• Under Request object signing algorithm, select a supported algorithm with which the request object will be signed.

• Under Request object encryption algorithm, choose a supported asymmetric encryption algorithm to perform the key exchange.

• Under Request object encryption method, choose a supported symmetric encryption algorithm with which the request object will be encrypted.

Access Token

The following configurations are related to the access token.

Token type

WSO2 Identity Server supports the following token types.

• Opaque: Opaque tokens are plain text tokens. If a resource server wants to know information related to an opaque token, it has to call the introspection endpoint and receive information related to tokens. An example for a opaque token response is shown below.

  {
  "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
  }
  

• JWT token: JWT tokens are self-contained verifiable access 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. An example for a JWT token response is shown below.

  {
  "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
  }
  

  
  

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.

Note

Learn more about Token Binding in WSO2 Identity Server.

WSO2 Identity Server 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 the 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.
certificate	Binds the token to the hash of the TLS certificate passed in the request. Supported with all grant types.
device-flow	Binds the token to the device_code sent in the device_flow grant type token call.
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://localhost:9443/oauth2/token Generally for applications that involve multiple instances and use back-channel grant types such as token exchange or password.

Note

You can configure the following properties related to token binding:

• Validate token bindings - When enabled, WSO2 Identity Server uses the selected binding type to validate the access token based on the binding information sent in the cookie.

• Revoke token upon user logout - When enabled, a user logout from a session causes access tokens to be revoked provided the logout request contains either client_id or id_token_hint. Learn more about logout requests.

User access token expiry time

This option specifies the validity period of an access token issued to a user in seconds. The default expiry time is 3600 seconds.

Application access token expiry time

This option specifies the validity period of an access token issued to an application when using the Client Credentials grant type in seconds.

ID Token

The following configurations are related to the ID token.

Audience

The audience specifies the recipient(s) for which the ID token is intended. By default, the client ID of the application is added as an audience. You can add multiple audiences in the ID token as shown below.

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://localhost:9443/oauth2/token",
 "exp": 1623847489,
 "iat": 1623843889
}

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://localhost:9443/oauth2/token",
 "exp": 1623912434,
 "iat": 1623908834
}

Enable encryption

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

Note

To enable this option, configure a certificate for your application in the Certificate section.

Algorithm

A single-use AES secret key, called the Content Encryption Key (CEK) is generated. WSO2 Identity Server obtains the public key from the specified certificate, and encrypts the CEK using the asymmetric encryption algorithm specified here. The selected algorithm is mentioned as the alg in the ID token header.

Encryption Method

The encryption method defines a symmetric encryption algorithm to encrypt the ID token.

WSO2 Identity Server uses the 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

This option specifies the validity period of the ID token in seconds. The default value is 3600 seconds.

Refresh Token

These configurations appear if the Refresh Token grant type is added as an allowed grant type.

Renew refresh token

By default, whenever the refresh token is exchanged for a new access token, WSO2 Identity Server issues the same refresh token back, as long as it is not expired.

If you select the Renew refresh token option, each time the refresh token is exchanged for a new access token, WSO2 Identity Server invalidates the existing refresh token and issues a new refresh token.

Refresh token expiry time

This option specifies the validity period of a refresh token in seconds. The default value is 86400 seconds.

Certificate

Certificates play a critical role in validating signatures on signed requests and encrypting sensitive information in requests. To add a certificate, you can either upload one or provide a JWKS endpoint.

To upload a certificate, select Provide certificate and upload a certificate in the .pem format.

How to convert .crt, .cer or .der to the .pem format?

You can use OpenSSL to convert certificates of other formats to the .pemformat using the following commands.

Convert CRT to PEM

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

Convert CER to PEM:

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

Convert DER to PEM:

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