> **Description:** Understand the fundamental OAuth2 and OpenID Connect concepts that power the Login API's authentication and authorization mechanisms. # 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](https://tools.ietf.org/html/rfc6749) 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](https://www.youtube.com/watch?v=996OiexHze0) by Nate Barbettini at Okta. We also recommend reading: * [OAuth 2 Simplified](https://aaronparecki.com/oauth-2-simplified) * [OAuth 2.0](https://oauth.net/2/) ## OpenID Connect [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) 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](https://developer.okta.com/blog/2017/07/25/oidc-primer-part-1) and [OpenID Connect explained](https://connect2id.com/learn/openid-connect). ## 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](https://tools.ietf.org/html/rfc6749#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](https://jwt.io/). Example header: ```json { "alg": "RS256", "kid": "public:80f3c34a-9779-4e1e-b645-117f3b771af8", "typ": "JWT" } ``` Example body: ```json { "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](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). It is important to validate the Id-token before using any data contained in it. See the OIDC standard on [Id-token validation](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation) 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](https://jwt.io/#libraries-io). #### ID token user info It is possible to configure whether the ID token includes userinfo on the [business portal](https://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: ```json { "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: ```json { "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](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/user-info.md#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`][access-token-endpoint] 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](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/browser-flow-integration.md#userinfo). Access tokens *must* be kept confidential in transit and storage. Example: ```text "hel39XaKjGH5tkCvIENGPNbsSHz1DLKluOat4qP-A4.WyV61hCK1E2snVs1aOvjOWZOXOayZad0K-Qfo3lLzus" ``` For more information see [RFC-6749 section 4.1.3-4.1.4](https://tools.ietf.org/html/rfc6749#section-4.1.3). ### 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 the [business portal](https://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](https://developer.vippsmobilepay.com/docs/APIs/login-api/login-api-faq.md#how-can-i-use-client_secret_post-for-authentication). For more information on the token endpoint, see [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) and [RFC-6749 section 3.2](https://tools.ietf.org/html/rfc6749#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](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/user-info.md#scopes). [access-token-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/login-swagger-id.yaml > **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).