Skip to main content

Core concepts

API version: 2.0

Login is to a large degree based on the OAuth2 and OpenID Connect standards. Some core concepts related to these are presented below.

OAuth 2.0​

OAuth 2.0 is the industry-standard protocol for authorization. Giving a proper introduction to the standard is out of the scope of this documentation, but there are many excellent resources on the web. If you are new to the subject, we recommend this talk by Nate Barbettini at Okta. We also recommend reading:

OpenID Connect​

OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. It enables Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in a REST-like manner.

Some good sources to get you started are: Identity, Claims, & Tokens – An OpenID Connect Primer and OpenID Connect explained.

Supported OpenID Connect flows​

Authorization code grant​

The authorization code grant type is used to obtain both access tokens and refresh tokens and is optimized for confidential clients. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner's user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server.

For more information see RFC-6749 section 4.1.

Tokens​

ID token​

The ID token is a signed information object representing the authenticated identity of the user. As part of the OpenID Connect standard, the ID token is encoded as a JWT and signed using the JWS standard. The ID Token can be decoded for debugging purposes by tools such as jwt.io.

Example header:

{
  "alg": "RS256",
  "kid": "public:80f3c34a-9779-4e1e-b645-117f3b771af8",
  "typ": "JWT"
}

Example body:

{
  "at_hash": "tyFnH20TOmPZkgJU8e5iKw",
  "aud": [
    "vipps-integration"
  ],
  "auth_time": 1557319296,
  "exp": 1557322938,
  "iat": 1557319338,
  "iss": "https://apitest.vipps.no/access-management-1.0/access/",
  "jti": "62a85e56-3d45-4c7e-a055-46932093257a",
  "nonce": "",
  "msn": "123456",
  "rat": 1557319255,
  "sub": "c06c4afe-d9e1-4c5d-939a-177d752a0944"
}

You can read more at the OIDC standard.

It is important to validate the Id-token before using any data contained in it. See the OIDC standard on Id-token validation for the specifics. We recommend that you use a library for this. A good place to start is finding a library for your language at jwt.io.

ID token user info​

It is possible to configure whether the ID token includes userinfo on portal.vippsmobilepay.com.

ID token without user info​

When the ID token configuration is set to exclude userinfo, the ID token will contain only the standard OpenID Connect claims:

{
  "at_hash": "tyFnH20TOmPZkgJU8e5iKw",
  "aud": [
    "vipps-integration"
  ],
  "auth_time": 1557319296,
  "exp": 1557322938,
  "iat": 1557319338,
  "iss": "https://apitest.vipps.no/access-management-1.0/access/",
  "jti": "62a85e56-3d45-4c7e-a055-46932093257a",
  "nonce": "",
  "msn": "123456",
  "rat": 1557319255,
  "sub": "c06c4afe-d9e1-4c5d-939a-177d752a0944"
}
ID token with user info​

When the ID token configuration is set to include userinfo, the ID token will include the userinfo claims directly in the token payload. The userinfo claims in the ID token have the same format as the response from the /userinfo endpoint.

Example ID token with userinfo:

{
  "at_hash": "c8TWrG6a1gOmsSmTDlWiMA",
  "sub": "123456-79f0-4e0a-9a35-3e39c5402650",
  "birthdate": "1931-07-25",
  "gender": "male",
  "iss": "https://ece46ec4-6f9c-489b-8fe5-146a89e11635.tech-02.net/access-management-1.0/access/",
  "msn": "12345",
  "sid": "a572828d-a303-4545-8709-f0867f5ce866",
  "nin": "11073100000",
  "azp": "edddb32f-5028-4397-b0ab-e8ecf218fdc2",
  "auth_time": 1758770735,
  "exp": 1758774335,
  "iat": 1758770735,
  "jti": "acc52f3c-3ea2-4739-8d16-1647a5ee7144",
  "email": "some@email.com",
  "other_addresses": [
    {
      "address_type": "work",
      "country": "NO",
      "formatted": "Test\n1780\nOslo\nNO",
      "postal_code": "1780",
      "region": "Oslo",
      "street_address": "Test"
    },
    {
      "address_type": "other",
      "country": "NO",
      "formatted": "Gate\n6362\nRegion\nNO",
      "postal_code": "6362",
      "region": "Region",
      "street_address": "Gate"
    }
  ],
  "address": {
    "address_type": "home",
    "country": "NO",
    "formatted": "Street\n0543\nOslo\nNO",
    "postal_code": "0543",
    "region": "Oslo",
    "street_address": "Street"
  },
  "email_verified": true,
  "rat": 71232147,
  "phone_number_verified": true,
  "given_name": "Some",
  "nonce": "bafe1f3b-081e-453a-870a-cabddac0f803",
  "aud": "uqwuer-12345-4397-b0ab-e8ecf218fdc2",
  "name": "Some Name",
  "phone_number": "123456789",
  "family_name": "Name"
}

For more information about the available userinfo claims and their formats, see User info: scopes.

Access token​

Access tokens are random strings that represent the authorization of a specific application to access specific parts of a user’s data.

These access tokens are provided by the POST:/access-management-1.0/access/oauth2/token endpoint. The token itself does not provide any information, but it can be used to fetch the data that the end-user has consented to share from the userinfo endpoint. Access tokens must be kept confidential in transit and storage.

Example:

"hel39XaKjGH5tkCvIENGPNbsSHz1DLKluOat4qP-A4.WyV61hCK1E2snVs1aOvjOWZOXOayZad0K-Qfo3lLzus"

For more information see RFC-6749 section 4.1.3-4.1.4.

Refresh token​

Login does not currently support refresh tokens.

Token endpoint authentication method​

The token endpoint is a standard OIDC endpoint used for requesting Access and ID Tokens. The default token endpoint authentication method is client_secret_basic.

It is possible to change the authentication method to client_secret_post on portal.vippsmobilepay.com. This setting will then apply to all login transactions on this sales unit. For more information on how to change the authentication method, see FAQ: How can I use client_secret_post for authentication.

For more information on the token endpoint, see OpenID Connect Core 1.0 and RFC-6749 section 3.2.

Scopes​

The scope determines what information the user is asked to share. It can include several values, separated by a space.

For a full list of scopes, see User info: scopes.

Last updated on