OpenID Connect

OpenID Connect enables users to grant external applications access to resources in Yggio in a secure way.

Yggio supports OpenID Connect with Authorization Code Flow, which requires your application to have a backend.

To use OpenID Connect you must create an RP (Relying Party) via the Yggio REST API. RP is what an application is called in the OpenID Connect specification. It is important that you save the secret that is created for use in your application backend. There is no way of retrieving your secret from Yggio if you lose it, the only solution then is to create a new RP.

Feel free to take a look at yggio service example to see an example of a working implementation.

How to use Yggio's OpenID Connector in your application

Below is a sequence diagram showing the OpenID Connect process, followed by a detailed description of the steps.

1. Gather the clientId and redirectUri of the RP you created previously, the URL for the authorization endpoint, and the scope you wish to request.
The URL and supported scopes can be found by making a request to auth/endpoints.
Having gathered the above, redirect the user to the authorization endpoint with the variables in query parameters. Optionally, a state param can also be sent to mitigate CSRF attacks.

<authorizationEndpoint>?client_id=<clientId>&redirect_uri=>redirectUri>&response_type=code&scope=<scope>&state=<state>

---

2. The redirection will move the user to a sign in page where the user can enter their username and password and login. This step is skipped if the user is already logged in.

---

3. The user is moved to a page where the user can choose to allow or deny the application to access their account. When the user presses "Allow" the user will be redirected to the redirectUri above, together with a generated code and the state used above. The state should be verified before accepting the code. <redirectUri>?code=<code>&state=<state>

---

4. The application can now send a POST request to the token endpoint (can be fetched from auth/endpoints). This request should be consist of the following:

headers: {
  'content-type': 'application/x-www-form-urlencoded'
},
data: {
  client_id: <clientId>,
  client_secret: <clientSecret>,
  code: <code>,
  grant_type: 'authorization_code',
  redirect_uri: <redirectUri>
}

The response should include these values (id_token will only show if it was requested as a scope):

{
  access_token,
  expires_in,
  refresh_expires_in,
  refresh_token,
  token_type: 'bearer',
  id_token,
  'not-before-policy',
  session_state,
  scope
}

where access_token, refresh_token and id_token are all JWTs (JSON Web Token)

---

5. The authorization process is now finished. The tokens and data should be saved so they can be used again. The access_token is used as an authorization header in requests to the Yggio REST API. Like so:

Authorization: Bearer <access_token>

The id_token can be used for authenticating the user and the refresh_token is used for refreshing the access token. See the following section.

Refreshing the access token

The access token is only valid for 30 days. To avoid demanding the user to login again, you can refresh the user's access token.

To refresh the access token the application sends the same request as the one in step 4, with the exception of the data instead containing the following:

  {
    client_id: <clientId>,
    client_secret: <clientSecret>,
    grant_type: 'refresh_token',
    refresh_token: <refresh_token>
  }