In a web single sign-on use case a single OAuth Client is registered with SSO. This client is a web application running on a web server.

The client wants to get an access token for calling the userinfo service of SSO. The userinfo service returns claims and attributes describing the authenticated user.

Contents


Sequence diagram of authorization code grant

Authorization Request

https://tools.ietf.org/html/rfc6749#section-4.1.1
http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest

GET /uas/oauth2/authorization

Required Parameters

response_type = code

For authorization code grant the value must be set to "code"

scope = openid

For web single sign-on use case the value is set to "openid"

client_id

OAuth Client Identifier of the web application. This value is generated by SSO management when the OAuth Client is registered and activated. See Client registration and activation - SSO.

redirect_uri

The redirect uri value must have been be registered with SSO management. The authorization server redirects the web browse to this address after authenticating the end-user. See Client registration and activation - SSO.

Optional Parameters

state

An opaque value used by the client to maintain state between the request and callback

nonce

An opaque value used to associate a client session with an ID Token, and to mitigate replay attacks

login_hint

The value from login_hint is put into the username field on the login form

acr_values

Choose authentication methods that may satisfy the request

ui_locales

Choose the locale used in the login form

max_age

Specifies the allowable elapsed time in seconds since the last time the user was authenticated. If the elapsed time is greater than this value, the user is re-authenticated.

prompt

Possible values: none, login, consent, select_acccount. Value none means that the user is not shown a login page at all, which means that user won't be attempted to authenticate unless they already have an existing authentication. Values login, consent and select_account all mean that user is always shown a login page, despite having an existing authentication or not.

display

Choose the UI template used in the login form. The template must contain the value of display parameter in the template setting oidc.display. For this setting, please refer to Ubisecure SSO Login UI Customization.

code_challenge

A challenge derived from the code verifier to be verified against when processing the subsequent token request. Required if a value is set for the key "code_challenge_method" or "token_endpoint_auth_method" is set to "none" in the Client Metadata. Otherwise optional.

See RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients.

code_challenge_method

A method that was used to derive code challenge. Allowed values are "plain" and "S256". If not set, then the default value is the value of the key "code_challenge_method" in the Client Metadata if present, or "plain". Furthermore, if the value "S256" is set for "code_challenge_method" in the Client Metadata, the use of "plain" code_challenge_method in the authorization request is not allowed.

See RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients.

Listing 1. Sample authorization request

GET 
https://sso.example.com/uas/oauth2/authorization?response_type=code&scope=openid&client_id=2001221477&redirect_uri=https://client.example.com/response&state=40e1bfc0-4587-4859-be08-a58e3fffa37a&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256

Authorization Response

https://tools.ietf.org/html/rfc6749#section-4.1.2
http://openid.net/specs/openid-connect-core-1_0.html#AuthResponse

Parameters

code

Authorization Code value generated by SSO

Optional Parameters

state

Value from authorization request

Listing 2. Sample authorization response

HTTP/1.1 302 Found
Location: https://client.example.com/response?state=40e1bfc0-4587-4859-be08-a58e3fffa37a&code=vn8DO49e%2bZasXSaS7zTNlaiq5Zr9kNdgDbPubfaz7w%2bwgbxHXx8pmuL1F9gvX0id

Access Token Request

https://tools.ietf.org/html/rfc6749#section-4.1.3
http://openid.net/specs/openid-connect-core-1_0.html#TokenRequest

Replaying the same authorization code revokes the previously issued access token for the replayed authorization code.

POST /uas/oauth2/token

Required Parameters

grant_type = authorization_code

For token request with authorization code the value must be set to "authorization_code"

Allowed by Default.

redirect_uri

The value must be the same that was used for authorization request. See Authorization request.

code

Authorization Code value received in Authorization Response. See Authorization request.

client_id & client_secret

OAuth Client Identifier and Secret of the web application as Client credentials. See Client registration and activation - SSO. Client authentication is disallowed if "token_endpoint_auth_method" is set to "none" in the Client Metadata and only client_id is to be sent.

Optional Parameters

code_verifier

A cryptographically random string that is used to match the code_challenge sent in the authorization request to the token request. Required, if code_challenge was sent. Disallowed, if code_challenge was not sent.

See RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients.

Listing 3. Sample token request

POST https://sso.example.com/uas/oauth2/token 
Authorization: Basic MTc2MjQxNDM3NDoqKio=
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&redirect_uri=https://client.example.com/response&code=QnKskjekHNhYlNKsD3pPKnJ4&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Access Token Response

https://tools.ietf.org/html/rfc6749#section-4.1.4
https://tools.ietf.org/html/rfc6749#section-5.1
http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse

Parameters

scope = openid

The requested scope value. See Authorization request.

expires_in

The lifetime in seconds of the access token

token_type = Bearer
access_token

Access Token issued by the authorization server

id_token

If requested scope contains value "openid" then id_token is returned

Optional Parameters

refresh_token

Refresh Token issued by the authorization server. The refresh token may be used in a refresh request to refresh the access token.

To see how the refresh token need to be set please refer to chapter OAuth 2.0 Client step 5 in Management UI Applications - SSO.

Listing 4. Sample token response (JSON reformatted for readability)

HTTP/1.1 200 OK
Content-Type: application/json 
{
    "scope": "openid",
    "expires_in": 3600,
    "token_type": "Bearer",
    "access_token": "DSJJU6QhquTUsznTDeDq0eVm",
    "id_token": "eyJhbGciOiJSUzI1NiJ9.eyJz..."
}

ID Token

http://openid.net/specs/openid-connect-core-1_0.html#CodeIDToken
http://openid.net/specs/openid-connect-core-1_0.html#IDToken

Parameters

sub

Value that identifies the end-user

iss

Issuer of this response. Appears as "issuer" in authorization server metadata. See chapter Metadata Response in OAuth 2.0 and OpenID Connect metadata - SSO.

aud

OAuth Client Identifier of recipient

exp

Expiration timestamp

iat

Time at which this response was issued

auth_time

Time when end-user was authenticated

amr

Authentication methods reference, expressed as JSON array

session_index

SSO session index identifier

Optional Parameters

acr

Authentication context class reference. If context class is configured in SSO then value appears here.

nonce

Value from authorization request. See Authorization request.

The ID Token may contain other name-value parameters (claims) as defined by SSO authorization policy.

UserInfo Request

http://openid.net/specs/openid-connect-core-1_0.html#UserInfoRequest

GET /uas/oauth2/userinfo

Required Parameters

bearer authorization header Access Token value received in Access Token Response.

Listing 5. Sample userinfo request

GET /uas/oauth2/userinfo HTTP/1.1
Host: sso.example.com
Authorization: Bearer DSJJU6QhquTUsznTDeDq0eVm

POST /uas/oauth2/userinfo

Required Parameters

bearer authorization header Access Token value received in Access Token Response.

Listing 5. Sample userinfo request

POST /uas/oauth2/userinfo HTTP/1.1
Host: sso.example.com
Authorization: Bearer DSJJU6QhquTUsznTDeDq0eVm

UserInfo Response

http://openid.net/specs/openid-connect-core-1_0.html#UserInfoResponse
http://openid.net/specs/openid-connect-core-1_0.html#IDToken

Parameters

sub

Value that identifies the end-user

iss

Issuer of this response. Appears as "issuer" in authorization server metadata. See chapter Metadata Response in OAuth 2.0 and OpenID Connect metadata - SSO.

aud

OAuth Client Identifier of recipient

exp

Expiration timestamp

iat

Time at which this response was issued

auth_time

Time when end-user was authenticated

amr

Authentication methods reference, expressed as JSON array

session_index

SSO session index identifier

Optional Parameters

acr

Authentication context class reference. If context class is configured in SSO then value appears here.

The userinfo response may contain other name-value parameters (claims) as defined by SSO authorization policy.

Listing 6. Example userinfo response (JSON reformatted for readability)

HTTP/1.1 200 OK
Content-Type: application/json 
{
	"sub": "***",
	"iss": "https://sso.example.com/uas",
	"aud": "2001221477",
	"exp": 1429700671981,
	"iat": 1429697071971,
	"auth_time": 1429697071527,
	"amr": ["https://sso.example.com/uas/saml2/names/ac/password.1"],
	"session_index": "0a9b62ce8de4"
}

Browser not supported