1. Home >
2. OpenId Connect >
3. API Reference - Latest >
4. Upgrade v1 to v2

Upgrade v1 to v2

---

There are several enhancements and breaking changes that you should consider when upgrading from version 1 of our OpenId Connect service to version 2.

Version 1 Deprecation

Version 1 of our OpenId Connect provider will be deprecated and no longer available as at April 20th 2021. This will impact all requests to

• https://openid-connect.onelogin.com/oidc - US / Global
• https://openid-connect-eu.onelogin.com/oidc - Europe

as well as version 1 when using the new style of Issuer endpoint mentioned in this document.

• https://{subdomain}.onelogin.com/oidc/1

Issuer Endpoint

With v1 we supported two Issuer endpoints.

• https://openid-connect.onelogin.com/oidc - US / Global
• https://openid-connect-eu.onelogin.com/oidc - Europe

This generally worked well but has some limitations around the use of custom domains as well as enabling easy upgrade paths to future features and provider versions.

Moving forward the recommended Issuer endpoint will contain your OneLogin subdomain as well as the version of the provider that you want to target.

e.g. https://{subdomain}.onelogin.com/oidc/{version}

Therefore to target the v2.0 endpoint using the acme subdomain you would use the following issuer endpoint.

https://acme.onelogin.com/oidc/2

With a custom domain the issuer endpoint would look like this.

https://my.custom-domain.com/oidc/2

Well Known Configuration Endpoint

For clients that support automatic discovery and configuration via the well-known configuration endpoint you will also need to switch to using a subdomain.

e.g.

https://.onelogin.com/oidc/2/.well-known/openid-configuration

Access Token

The v1 Access Token was a short string value, but the v2.0 Access Token is much longer. If you have sized a database column based on the v1 token you may need to increase that field size.

The reason for the increased size of the Access Token is that it’s now a JSON Web Token (JWT). This is useful as a Bearer token for authorizing API requests within your applications or against API gateways.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkpSY080bnhzNWpnYzhZZE43STJoTE80Vl9xbDFiZG9pTVhtY1lnSG00SHMifQ.eyJqdGkiOiJ1N2FTRDgyNFdrSnd0d3ZuZzZObWYiLCJpc3MiOiJodHRwczovL29wZW5pZC1jb25uZWN0Lm9uZWxvZ2luLmNvbS9vaWRjIiwiaWF0IjoxNTM0ODExODI2LCJleHAiOjE1MzQ4MTI0MjYsImF1ZCI6IjlhNmQ2MzUwLTJhZjgtMDEzNi0xOTdiLTA2YWNjNzZkMzRiNDkyOTIwIn0.VtybpMirTTrRGiYsJfX-yIjVkqkuyc1gj7pbim0ecOde3ku75Zvyh42nxkKdxxzBuMvWZpulpiaFru6ZAnd6MxZj9VyKmqZ3xFhBr0GRKzScRJjnX2_cAHCJtr7AqwxolaGsu4iZUolOrTdhX1BU3skLvNYE05TdeEITUsilEPL0ew5VV8MzYFQkY7Grr47MxpwEUv7yT6C3pz87Bgg5_7zFPHpLLeCRC8bhMK0rRe9uyK9ExQKIkLlf5Hyh1gfWqrTYwgXfIQt1Ba7IiAMAQvN60VTDbSxLBl0_x-vE-ezVfyHkN4d6owF37wOruoLsZ8c1braUNOWY00xkPwxxTQ",
  ...
}

The content of the standard JWT Access Token looks like this.

{
  "jti": "u7aSD824WkJwtwvng6Nmf",
  "iss": "https://openid-connect.onelogin.com/oidc",
  "iat": 1534811826,
  "exp": 1534812426,
  "aud": "9a6d6350-2af8-0136-197b-06acc76d34b492920"
}

The signature of the token can be verified using the standard JWKs endpoint https://{subdomain}.onelogin.com/oidc/2/certs.

To use the Access Token for authorization with an API gateway you may want to customize the audience, claims and scopes.

e.g.

{
  "email_address": "tommy@onelogin.com",
  "jti": "HlKVBL__W1pdAe0BOjwDe",
  "sub": "35666371",
  "iss": "https://sharkbytes.onelogin.com/oidc/2",
  "iat": 1573508187,
  "exp": 1573509087,
  "scope": "openid profile read:contacts",
  "aud": [
    "http://myapi.com/contacts"
  ],
  "azp": "78d1d040-20c9-0136-5146-067351775fae92920"
}

See the Api Authorization docs for details about customizing these tokens.

ID Token

The id_token contains an updated_at attribute which indicates the last time the user record was updated.

Previously updated_at was an ISO8601 formatted date. It is now a number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

e.g.

{
    "updated_at": 1573776723
}

Refresh Token

With the Password Grant the refresh_token was only returned if a Refresh Token Expiry value was set in the OIDC app configuration. If the no value was set the refresh_token would not be returned.

With v2 the Refresh Token Expiry is not longer used to control if the refresh_token should be returned or not. You must supply the offline_access scope if you wish to obtain a Refresh Token.

e.g.

scope=openid profile offline_access

Token Expiration

The Refresh Token and Access Token expiration settings now apply to all grant types.

These expiration values can be set on the OIDC app either via the Admin UI or the Apps API.

The ID Token expiry will be set to the same value as the Access Token expiry.

Password Grant

The id_token is now returned with Password Grant requests.

Profile Scope

When using the profile scope on v1 a number of user claims are returned that should not be according to the OIDC specification.

We have remove the following claims from the profile scope on v2.

• company
• department
• title
• custom_fields

This is reflected in both the id_token and the User Info endpoint.

If you need to make use of these fields then create them as parameters on your OIDC app and use the params scope to have them included.

---