OpenID Connect Flow

Summary

OpenID connect is an extension on top of OAuth2, so the authorization and token enpoints are the same as described in OAuth2 Introduction. Currently the OpenID Connect implementation in Agate only supports the authorization code flow.

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 (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"
}