OpenID Connect
This section describes the OpenID Connect API's provided by the Token Server. It's divided into the following subsections:
- OpenId authorization endpoint
- OpenId token endpoint
- OpenId JWKs endpoint
- Dynamic Client Registration
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"
}
]
}
JWK object specification can be found here.
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"}
}
Detailed OpenIdConnect DCR documentation can be found here.