OpenID Connect

This section describes the OpenID Connect API's provided by the Token Server. It's divided into the following subsections:

Token Server does supports the OpenId Connect authorization. To initialize the flow "openid" scope which informs the Token Server that the client is making an OpenID Connect request, and requests access to the authenticated user’s ID. You must include this scope with the other OpenID Connect scopes.

OpenId authorization endpoint

Authorization code flow

OpenId authorization code flow may be initiated by providing the "openid" scope and "code" response_type params within the authorization request. The openId authorization code will respond with id_token and access/refresh token after calling the /token endpoint.

Example openId authorization code flow request

GET /oauth/authorize
?response_type=code
&client_id=8DE850A0B2888055C8BF23502845DFF3599423F1CA45C8CF88D96C3DCB53D5FE
&redirect_uri=https://oauth-engine.onegini.com/client/redirect
&scope=openid read
&state=067e0e69-eed0-4349-afae-0b55e5b953a

Example openId authorization code flow response

HTTP/1.1 302 Found
  Location: https://oauth-engine.onegini.com/client/redirect?
    code=SplxlOBeZQQYbYS6WxSbIA
    &state=af0ifjsldkj

Implicit flow

When using the Implicit Flow, all tokens are returned from the Authorization Endpoint; the Token Endpoint is not used.

The Implicit Flow is mainly used by Clients implemented in a browser using a scripting language. The Access Token and ID Token are returned directly to the Client, which may expose them to the End-User and applications that have access to the End-User's User Agent. The Token Server does not perform Client Authentication.

Example openId implicit code flow request

GET /oauth/authorize
?response_type=token id_token
&client_id=8DE850A0B2888055C8BF23502845DFF3599423F1CA45C8CF88D96C3DCB53D5FE
&redirect_uri=https://oauth-engine.onegini.com/client/redirect
&scope=openid read
&state=067e0e69-eed0-4349-afae-0b55e5b953a

Example openId implicit code flow response

HTTP/1.1 302 Found
  Location: https://oauth-engine.onegini.com/client/redirect#
    access_token=SlAV32hkKG
    &token_type=bearer
    &id_token=eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso
    &expires_in=3600
    &state=af0ifjsldkj

Implicit flow is being controlled by the response_type parameter value:

response_type - REQUIRED. OAuth 2.0 Response Type value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints used. When using the Implicit Flow, this value is id_token token or id_token. The meanings of both of these values are defined in OAuth 2.0 Multiple Response Type Encoding Practices. No Access Token is returned when the value is id_token.

Note: While OAuth 2.0 also defines the token Response Type value for the Implicit Flow, OpenID Connect does not use this Response Type, since no ID Token would be returned.

Hybrid flow

Currently not supported.

OpenId token endpoint

Token endpoint is used only in authorization code flow. The endpoint will respond with id_token additionally to access or refresh tokens.

Example openId authorization code flow token request

POST /oauth/token HTTP/1.1
Host: onegini.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
    code=i1WsRn1uB1&
    client_id=s6BhdRkqt3&
    client_assertion_type=
    urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
    client_assertion=PHNhbWxwOl ... ZT

Example openId authorization code flow token response

HTTP/1.1 200 OK
 Cache-Control: no-store
 Content-Type: application/json
 Pragma: no-cache
 {
     "access_token": “O91G451HZ0V83opz6udiSEjchPynd2Ss9......",
     "token_type": "Bearer",
     "expires_in": "3600",
     "refresh_token": "8722gffy2229220002iuueee7GP...........",
     "id_token" : "eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso"
 }

OpenId JWKs endpoint

To retrieve a set of JWKs (JSON Web Key) objects used in id_token signing/encryption process client need to perform an endpoint call:

Endpoint: GET /oauth/jwk/{clientId}.jwks

Parameter Description
clientId ClientId requesting JWKs

The endpoint is public and doesn't require any authentication.

Client specific endpoint address is being returned during Dynamic Client Registration process (#jwks_uri property).

Example openId JWK request

GET /oauth/jwk/DF4B0DFDCD99A82C9E23C5D6EBD2515900C1C63CFBD86D7724153147D154C779.jwks HTTP/1.1
Host: onegini.example.com
Content-Type: application/json
Example of openId successful jwk response
HTTP/1.1 200 OK
 Cache-Control: no-store
 Content-Type: application/json
 Pragma: no-cache
{
    "keys": [
        {
            "alg": "ES512",
            "crv": "P-521",
            "kty": "EC",
            "use": "sig",
            "y": "HkM7iYS-GVLSCvAK47NS7YKkcoM9v3wfmdONHXDTCjQ",
            "x": "dXPobU__T7wAfE9KgDlOQkUBve1qe26mwitr7By-f20"
        }
    ]
}

Read the JWK object specification for a detailed description.

Example openId jwk error response

HTTP/1.1 200 OK
 Cache-Control: no-store
 Content-Type: application/json
 Pragma: no-cache

Note: Due to a fact that the endpoint is publicly available it doesn't return any error codes/messages.

Dynamic Client Registration

DCR of openId enabled clients will result in return of client specific metadata object. The standard DCR process is also described in point 5 of this document.

Example openId specific DCR successful response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "issuer":"oauth-engine.onegini.com",
    "id_token_encrypted_response_enc":"No encryption",
    "token_endpoint":"/token",
    "id_token_signed_response_alg":"ES256",
    "id_token_encrypted_response_alg":"No encryption algorithm",
    "client_secret_expires_at":0,
    "response_types_supported":["token id_token","token","code","id_token"],
    "jwks_uri":"oauth-engine.onegini.com/oauth/jwk/5A76FFAF480D570C62FA345F2EF704A19FF0A267F85AE8F861CAFA26EB17A094.jwks",
    "authorization_endpoint":"/authorize",
    "client_id":"5A76FFAF480D570C62FA345F2EF704A19FF0A267F85AE8F861CAFA26EB17A094",
    "client_secret":"1AA83D8A5032A868D52130E0C42528B11D5E10234F51A9DA8DFE9C1AB421EDCC"}
}

Read the OpenIdConnect DCR documentation for more details.