Authentication Service

Introduction to Authentication Service

Our simple authentication service let your customers/end-users create account and use the same account to login to your multiple applications as MyPage, Loyalty apps, Online store etc.

How it works

In a single-page application (SPA):

The user enters email/password in a login form hosted on the SPA and POST the details to the login resource.
API responds with the user’s access token.

A client with scope accounts:auth:users is required to access the login resource. Additional scopes must be added to grant access to user specific resources.

scope	description
`accounts:auth:users`	grant access to login and creating new user
`customer_customers:read`	grant `read-only` to user
`customer_customers:write`	grant `write-only` to user
`customer_discounts:read`	grant `read-only` to user discounts
`customer_receipts:read`	grant `read-only` to user receipts
`create:accounts:auth:refresh_token`	enable issuing `refresh_token`

Note: A login client with required grants can be created in backoffice.

In the SPA, use the “login client” to get an access token. The access token is required as authentication when accessing the login resource.

curl -X POST https://{server}/v1/accounts/{aid}/auth/token \
  -H 'Content-Type: application/json' \
  -u client_id:client_secret \
  -d '{"grant_type":"client_credentials", "audience":"{audience}" }'

where audience is the audience that was used when creating the login client. Use the access token when requesting login of a user:

curl -X POST https://{server}/v1/accounts/{aid}/customers/login \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {client_access_token} \
  -d '{"email":"", "password": "", "type": "", "audience":"{audience}"}'

A user access token will be returned on success.

Note: The user password must be set when creating the user.

Reset password

Reset of user password is done in three steps

Request change password, the user will receive a verification code via email.
Login the user by verification code:

curl -X POST https://{server}/v1/accounts/{aid}/auth/token
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {client_access_token} \
  -d '{"grant_type":"authorization_code", "audience":"{audience}", "verification_code: "" }'

Update the user with change password.

Refresh Token

A Refresh Token allows the application to ask Account-Auth service to issue a new Access Token without having to re-authenticate the user. This will work as long as the Refresh Token has not been revoked.

Note A Single-Page Application should not ever receive a Refresh Token, this information is sensitive and should not be exposed client-side in a browser.

Get a Refresh Token

To get a Refresh Token, you must use a client with a grant that includes the

create:account:auth:refresh_token

scope when requesting for a token.

curl -X POST https://{server}/v1/accounts/{aid}/customers/login \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {client_with_refresh_scope_access_token} \
  -d '{"email":"", "password": "", "type": "", "audience":"{audience}"}'

The response should contain an Access Token and a Refresh Token

{
    "access_token": "eyJhbGci...t7P4",
    "refresh_token": "eyGmkde...t3M3",
    "token_type": "Bearer",
    "expires_in": 86400
}

Note: Refresh Token must be stored securely by an application since they allow a user to remain authenticated essentially forever

Use a Refresh Token

To exchange the Refresh Token you received during authorization for a new Access Token, make a POST request to the /accounts/{oid}/auth/token endpoint using grant_type=refresh_token.

curl -X POST https://{server}/v1/accounts/{aid}/auth/token \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {client_with_refresh_scope_access_token} \
  -d '{"grant_type":"refresh_token","refresh_token":"eyGmkde...t3M3"}'

The response include a new Access Token, its type, its lifetime (in seconds)

{
    "access_token": "eyJhbGci...t7P4",
    "token_type": "Bearer",
    "expires_in": 86400
}

You should only ask for a new token if the Access Token has expired. For example, it’s a bad practice to call the endpoint to get a new Access Token every time you call an API.

Revoke a Refresh Token

Since Refresh Token never expire, it is essential to be able to revoke them in case they get compromised. You can revoke a refresh token by making a POST request to the /accounts/{oid}/auth/token endpoint using token=REFRESH_TOKEN_TO_REVOKE

curl -X POST https://{server}/v1/accounts/{aid}/auth/token \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {client_with_refresh_scope_access_token} \
  -d '{"token":"eyGmkde...t3M3"}'

How it works

In a single-page application (SPA):

The SPA creates a login link to login with Vipps
The user opens the login link and completes the login in the Vipps App
The SPA handles the redirect from Vipps and request access token via the API

{
  "client_id": "{client_id}",
  "audience": "{audience}",
  "type": "authorization_code",
  "scope": [
    "user:customers",
    "user:customers:/users?type=customer&phone_number"
  ],
  "oidc": {
    "authority": "https://api.vipps.no/access-management-1.0/access/.well-known/openid-configuration",
    "client_id": "{vipps-client-id}",
    "client_secret": "{vipps-client-secret}"
  }
}

You can continue to support existing login with email or phone number by including the grant scopes:

user:customers:/users?type=customer&phone_number
user:customers:/users?type=customer&email

The Vipps user will then be matched with existing user by matching the email or phone number provided by VippsUser consent is required when matching email or phone number Vipps documentation

Use the authorize with OIDC endpoint to create a Vipps Login URL

GET: /auth/oidc/authorize?client_id={client_id} \
  &response_type=code&scope={scopes}&state={state} \
  &redirect_uri={redirect_uri}

Query parameter examples

query parameters	example
audience	`{dintero-grant-audience}`
response_type	code
client_id	`{dintero-client-id}`
state	`{spa-generated-state}`
redirect_uri	`{vipps-redirect-uri}`
scope	`{vipps-scopes}`

See Vipps documentation for supported query parameters

After a successful authentication, the user agent is redirected to the {vipps-redirect-uri} with the following parameters added to the query

query parameters	example
code	Authorization code generated by Vipps
state	The exact value received from the client during authorization

Use the token verified by OIDC endpoint to get the user token

{
  "grant_type": "authorization_code",
  "code": "{code}",
  "client_id": "{dintero-client-id}",
  "redirect_uri": "{vipps-redirect-uri}",
  "audience": "{dintero-grant-audience}"
}

The response will look like this:

{
  "access_token": "eyJhbGci...t7P4",
  "token_type": "Bearer",
  "expires_in": 86400,
  "user_info": {
    "authority": "https://identityserver.example.com/access",
    "value": {
      "sub": "c06c4afe-d9e1-4c5d-939a-177d752a0944",
      "name": "Ada Lovelace"
    }
  }
}

Getting Started

Auth Service

Customers & Users

Discounts & Rewards

Receipts

Gift Cards

Introduction to Authentication Service

How it works

Reset password

Refresh Token

Get a Refresh Token

Use a Refresh Token

Revoke a Refresh Token

How it works

​Introduction to Authentication Service

​Add login to Your Single-Page App

​How it works

​Configure a login client

​Login user with email/password

​Reset password

​Refresh Token

​Get a Refresh Token

​Use a Refresh Token

​Revoke a Refresh Token

​Add Vipps Login

​How it works

​Configure grant for the login client

​Create Vipps Login URL

​Get user token from Vipps login

Introduction to Authentication Service

Add login to Your Single-Page App

How it works

Configure a login client

Login user with email/password

Reset password

Refresh Token

Get a Refresh Token

Use a Refresh Token

Revoke a Refresh Token

Add Vipps Login

How it works

Configure grant for the login client

Create Vipps Login URL

Get user token from Vipps login