Authentication Service

Introduction to Authentication Service Introduction

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.

Add login to Your Single-Page App

How it works

In a single-page application (SPA):

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

Configure a login client

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.

Login user with email/password

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

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

curl -X POST https://{serer}/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: "" }'

3. 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"}'

Add Vipps Login

How it works

In a single-page application (SPA):

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

Configure grant for the login client

Login with Vipps requires a client grant with oidc configured

{
  "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}"
  }
}

info

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 Vipps

User consent is required when matching email or phone number Vipps documentation

Create Vipps Login URL

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

Get user token from Vipps login

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"
    }
  }
}