OpenID Connect Flow¶
Summary¶
OpenID connect is an extension on top of OAuth2, so the authorization and token endpoints are the same as described in OAuth2 Introduction. Currently the OpenID Connect implementation in Agate only supports the authorization code flow.
Agate implements the OpenID Connect configuration discovery specification (scopes, endpoints, algos etc.). The discovery request would look like:
GET https://agate.example.org/.well-known/openid-configuration
Step 1. Authorization¶
This first step is the same as in the one in the Authorization Code Grant Flow: see authorization request and response. The scope to be requested must contain at least openid in addition to more specific scopes. Currently the only supported scopes are: email and profile.
Scope | Description |
---|---|
openid |
User name (required). |
email |
User email address and whether this email was verified (optional). |
profile |
User first and last names, groups (optional). |
phone |
User phone (not supported). |
address |
User address (not supported). |
An example of an OpenID connect authorization request will then look like:
GET https://agate.example.org/ws/oauth2/authorize?client_id=xxx&response_type=code&scope=openid+email+profile
Step 2. ID Token Issuing¶
This second step is similar to the access token issuing. When the authorization includes the openid scope, the response will contain an additional id_token in JWT format. An example of the reponse is:
{
"access_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMSIsImlzcyI6ImFnYXRlOjU3MDUyMjA2ZTRiMGRlNDNlYzE5NzM2YiIsImlhdCI6MTQ2MDA0MTU4NCwiZXhwIjoxNDYwMDcwMzg0LCJqdGkiOiI1NzA2Nzc3MGU0YjBmZjM3ODJkYmQ2MjIiLCJhdWQiOlsiZHJ1cGFsIl0sImNvbnRleHQiOnsic2NvcGVzIjpbIm9wZW5pZCJdLCJ1c2VyIjp7Im5hbWUiOiJKb2hubnkgQi4gR29vZCIsImxhc3RfbmFtZSI6Ikdvb2QiLCJncm91cHMiOlsibWljYS11c2VyIl0sImZpcnN0X25hbWUiOiJKb2hubnkgQi4ifX19.7SblBktnvXaoBFL61Rx_jb6PXXYPr4TFMlyi4ZYP5xE",
"id_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMSIsImlzcyI6ImFnYXRlOjU3MDUyMjA2ZTRiMGRlNDNlYzE5NzM2YiIsImdpdmVuX25hbWUiOiJKb2hubnkgQi4iLCJmYW1pbHlfbmFtZSI6Ikdvb2QiLCJuYW1lIjoiSm9obm55IEIuIEdvb2QiLCJlbWFpbCI6ImpvaG55Lmdvb2RAZXhhbXBsZS5jb20iLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImlhdCI6MTQ1OTk3Mzc1OCwiZXhwIjoxNDY3NzQ5NzU4LCJhdWQiOiJkcnVwYWwifQ.1IqjodUNGZ8pKnlxmjzR0XcDgs8Hnl-ufeFsSNH3qaA",
"expires_in": 28799,
"token_type": "bearer"
}
The id_token represents the following structure (when using scope=openid email profile):
{
"alg": "HS256"
}
.
{
"sub": "user1",
"iss": "agate:57052206e4b0de43ec19736b",
"given_name": "Johnny B.",
"family_name": "Good",
"name": "Johnny B. Good",
"email": "johny.good@example.com",
"email_verified": false,
"iat": 1459973758,
"exp": 1467749758,
"aud": "drupal"
}
.
[signature]
Step 3. ID Resource Access¶
In addition to the id_token included in the access token response, the user information can be retrieved from the UserInfo end point. This step is similar to the resource access one (the resource is then the user information).
An example of ID resource request is:
curl -X GET --header "Authorization: Bearer ACCESS_TOKEN" https://agate.example.org/ws/oauth2/userinfo
The response is in JSON format and contains the user profile claims. An example of a response is:
{
"family_name": "Good",
"sub": "user1",
"iss": "agate:57052206e4b0de43ec19736b",
"email_verified": false,
"given_name": "Johnny B.",
"email": "johny.good@example.com",
"name": "Johnny B. Good"
}