Configuring OIDC Authorization Code flow

This howto will show you how to configure basic OIDC Authorization Code flow. For other configuration options see here.

The purpose of Authorization Code flow is for users to provide one set of credentials to access multiple sites. Each time user wants to sign into an application or service using OIDC, they are redirected to their identity provider (IdP), where they authenticate and are then redirected back to the connected application (aka relying party "RP", service provider "SP") they want to use.

Steps to set up Authorization Code

Prerequisites
CAS configuration
Testing

Prerequisites

The tutorial uses following values and examples. Change them according to your environment.

Table 1. Configuration values used throughout the tutorial
Item	Value in examples
Appliance hostname on which the IdP is available	`iam-appliance.tld` You must always use the full hostname. NetBIOS-style (or other) hostname fragments that do not specify the domain are not supported.
File with OIDC client registration	`oidctest-201.json`

Create user for testing

Use the IdM to create dedicated user for testing. Set user’s password and make a note of it, as you will need it later.

Web browser

Your WEB browser has to be able to connect to appliance URL, i.e. https://iam-appliance.tld.

Web application to connect

You can set up an OIDC application if you want. However, this howto does not need it as the testing can be done only with a web browser and curl.

CAS configuration

The IAM appliance comes with preconfigured defaults. The bare minimum you need to do is to register your OIDC application using CAS’s service registration file.

HTTP Endpoints and Issuer

HTTP endpoints and Issuer identity are auto-configured as follows. Hostname of the server is taken from your deployment settings, in our example it is iam-appliance.tld.

Parameter

Value

OIDC Issuer

https://iam-appliance.tld/cas/oidc

Authorize endpoint

https://iam-appliance.tld/cas/oidc/authorize

Token endpoint

https://iam-appliance.tld/cas/oidc/token

Userinfo endpoint

https://iam-appliance.tld/cas/oidc/profile

Registering OIDC service

Create service registration file for the OIDC oidctest-201.json and place it into /data/volumes-shared/cas-services/ directory.

Example service registration file.

{
  "@class" : "org.apereo.cas.services.OidcRegisteredService",
  "clientId": "rlc-oidc-test",
  "clientSecret": "rlc-test",
  "serviceId" : "^https://your.application.url",
  "name": "OIDC-RLC",
  "id": 201,
  "subjectType": "pairwise",
  "bypassApprovalPrompt": true,
  "scopes" : [ "java.util.HashSet", [ "profile", "email", "address", "openid"  ]],
  "supportedGrantTypes": [ "java.util.HashSet", [ "AUTHORIZATION_CODE", "REFRESH_TOKEN" ] ],
  "supportedResponseTypes": [ "java.util.HashSet", [ "CODE", "TOKEN" ] ],
  "attributeReleasePolicy" : {
          "@class" : "org.apereo.cas.services.ReturnAllAttributeReleasePolicy"
  }
}

Table 2. Parameter definitions.
Parameter	Value
clientId	OIDC `client_id`. ASCII string. This value is assigned by CAS administrator, every OIDC client has its own.
clientSecret	OIDC `client_secret`. This value is assigned by CAS administrator. Every client has its own. Secret must be safely stored on application server. In no case should it be visible to the user of the application.
serviceId	OIDC `redirect_uri`. CAS allows this field to be a regular expression, therefore supporting multiple values and (to some extent) dynamic URLs. Supplied by the author of the external application.
name	Name of the service the CAS will show to the user.
id	Unique id of application in CAS. The id must match the number specified in the filename. In our case, the file is `oidctest-201.json`, so the id must be `201`.
scopes	List of OIDC `scopes` the client is allowed to use. The scope `openid` is mandatory, other scopes are optional or custom. You can read more on the subject in the official OIDC guide.
supportedGrantTypes	What OIDC grants the client is allowed to use. If you do not know what this is, leave it be.
supportedResponseTypes	What protocol responses the client is allowed to get from CAS. If you do not know what this is, leave it be.
bypassApprovalPrompt	Whether to ask user for explicit authorization of data passed between the IdP and SP. This is to turn on/off the data confirmation window. If you use OIDC to create corporate SSO where the SP is also provided by your company, you usually do not want to bother users with this.
attributeReleasePolicy	Which user attributes are to be released by CAS. You can influence this behavior by using `scope` parameter or by using scope-less claims. But those two approaches do not mix well.

Additional parameters

The service definition file may contain many more parameters as stated in the official CAS documentation.

Extending the configuration in such way may not be officially supported by the IAM appliance, though.

Testing

The Authorization Code flow works like this:

User accesses the SP.
If the user is not logged in, the SP redirects him to the IdP.
(optionally) User logs into the IdP.
(optionally) User authorizes the data set which will be handed over to the SP.
IdP issues one-time code and redirects user back to the SP.
SP contacts IdP (backend-to-backend) and exchanges code for an access token and optional refresh token.
SP contacts IdP (backend-to-backend) and uses access token to obtain user profile information.

Testing the flow

Paste following line into your browser. Adjust values according to your configuration.
```
https://iam-appliance.tld/cas/oidc/authorize?response_type=code&client_id=rlc-oidc-test&redirect_uri=https://your.application.url&scope=openid&state=789456
```
- The state is recommended parameter that protects the flow against CSRF attacks. For more information see here. (State parameter can be omitted while testing.)
- If you use multiple scopes, adjust the scope parameter accordingly.
If you are not already logged in, CAS displays a login screen. Log in with your test user.
After successful login, CAS issues the code and redirects you to the SP. The URL will look like this:
```
https://your.application.url/?code=OC-1-151iQqGjQW3em0UWQ-Zvp9iChhxIc&state=789456
```
Now, copy the value of code parameter. Validity of code is time-limited to about 30 seconds so you have to be quick.

And paste the code into the token request…

curl -k -XPOST --data "grant_type=authorization_code&redirect_uri=https://your.application.url&client_id=rlc-oidc-test&scope=openid&client_secret=rlc-test&code=OC-1-151iQqGjQW3em0UWQ-Zvp9iChhxIc" "https://iam-appliance.tld/cas/oidc/token"

If you use multiple scopes, adjust the scope parameter accordingly.

…and obtain the access token and OIDC id_token.

{
  "access_token":"AT-1-j3EPvr3jfHIVXEPnn4M8L-vMzg5L",
  "id_token":"eyJhbG... abbreviated ...8x8nAs6CaojdCw1YkFTv3qQu5VYCos_kn_f8uoHzCVkA",
  "token_type":"bearer",
  "expires_in":28800,"scope":"openid"
}

Finally, use the access token to obtain user profile information. The response will contain attributes from all scopes the access token was issued for.
```
curl -k -XGET --header "Authorization: Bearer AT-1-j3EPvr3jfHIVXEPnn4M8L-vMzg5L" https://iam.appliance.tld/cas/oidc/profile
```

User profile is returned.

{
  "sub":"idmtestuser",
  "service":"https://your.application.url",
  "auth_time":1670487660,
  "id":"idmtestuser",
  "client_id":"rlc-oidc-test",
  "attributes":{
    ... user attributes listed here ...
  }
}