OAuth 2.0 and OpenID Connect API

OAuth 2.0

According to RFC6749, OAuth 2.0 is an authorization framework that enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

OAuth 2.0 RFC defines multiple ways an application can get an access token, and it refers to it as grant_types. The protocol defines four grant types, which OneWelcome implements, such as:

• Authorization Code
• Implicit
• Resource Owner Password Credentials
• Client Credentials

You may ask yourself, why do we have all these ways for issuing an access token? Well, these grants serve different purposes, meaning different grants are suited for different use cases, such as web applications, server-to-server applications, or devices which are not able to launch a web browser.

Endpoints

OneWelcome implements the endpoints defined by OAuth 2.0 and OpenID Connect RFC, the full API definition can be found in OAuth 2.0 & OpenID Connect API specifications.

How does authorization code (AC) grant work?

Authorization code (AC) grant is used by web and mobile application, and as the name states, there is an authorization code issued by the authorization server which the client application exchanges it for an access token.

A step by step flow for issuing an access token using the AC grant can be seen below:

User has an active session:

1. User opens a browser and is accessing an application
2. Application is making an authorization request to the authorization server (AS)
3. User is already logged in and AS issues an authorization code
4. AS redirects the user to the application with the authorization code
5. Application exchanges the authorization code for an access token

User does not have an active session:

1. User opens a browser and is accessing an application
2. Application is making an authorization request to the authorization server (AS)
3. User is not logged in, and AS redirects the user to the login page
4. User authenticates with one of the configured login options
5. Once is successfully authenticated, AS will issue an authorization code
6. AS redirects the user back to the application with the authorization code
7. Application exchanges the authorization code for an access token

What API do you need?

For sending the authorization request, the authorize API is needed, and for exchanging the authorization code for an access token, token API is required.

Example of authorization request:

curl --request GET \

  --url 'https://www.onewelcome.com/onewelcome-dev/auth/oauth2.0/v1/authorize?response_type=code&client_id=myoauth2client&redirect_uri=https://www.myapp.com&scope=profile&state=dasdassd-qedsaasdd-dadas'

Example of response on authorization request in case the user is not authenticated:

< HTTP/2 302 

< location: https://www.onewelcome.com/onewelcome-dev/login/?sessionOnly=true&goto=https%3A%2F%2Fwww.iwelcome.com%2Fiwelcome-dev%2Fauth%2Foauth2.0%2Fv1%2Fauthorize%3Fresponse_type%3Dcode%26client_id%3Dmyoauth2client%26redirect_uri%3Dhttps%253A%252F%252Fwww.myapp.com%26scope%3Dprofile%26state%3Ddasdassd-qedsaasdd-dadas

Example of response on authorization request in case the user is authenticated:

< HTTP/2 302 

< location: https://www.myapp.com?code=3eccd9ca-4d1c-4584-ac31-9bb8442c7f6d&scope=profile&iss=https%3A%2F%2Fwww.onewelcome.com%2Fonewelcome-dev%2Fauth%2Foauth2.0&state=smth&client_id=myoauth2client

Example of token request:

curl --request POST \

  --url https://www.onewelcome.com/onewelcome-dev/auth/oauth2.0/v1/token \

  --header 'Content-Type: application/x-www-form-urlencoded' \

  --data grant_type=authorization_code \

  --data code=3eccd9ca-4d1c-4584-ac31-9bb8442c7f6d \

  --data redirect_uri=https://www.myapp.com \

  --data client_id=myoauth2client \

  --data client_secret=somesecret

How does OAuth 2.0 implicit grant works?

According to RFC6749 ,the implicit grant is a simplified authorization code flow optimized for clients implemented in a browser using a scripting language such as JavaScript. In the implicit flow, instead of issuing the client an authorization code, the client is issued an access token directly.

A step by step flow can be seen below:

1. User opens a browser and is accessing an application
2. Application is making an authorization request to the authorization server (AS)
3. If user is already logged in and AS issues an access token, otherwise the user will be redirected to the login page asking for login, and once logged in it will issue an access token
4. AS redirects the user to the application with the access token

What API do you need?

For the implicit grant, only the authorization endpoint is needed, since the response_type=token indicates that the implicit grant is used.

Example of authorize request:

curl --request GET \

  --url 'https://www.onewelcome.com/onewelcome-dev/auth/oauth2.0/v1/authorize?response_type=token&client_id=myoauth2client&redirect_uri=https%3A%2F%2Fwww.myapp.com&scope=email' \

  --header 'Content-Type: application/x-www-form-urlencoded'

Example of response when the user is not authenticated

< HTTP/2 302 

< location: https://www.onewelcome.com/onewelcome-dev/login/?sessionOnly=true&goto=https%3A%2F%2Fwww.iwelcome.com%2Fiwelcome-dev%2Fauth%2Foauth2.0%2Fv1%2Fauthorize%3Fresponse_type%3Dtoken%26client_id%3Dmyoauth2client%26redirect_uri%3Dhttps%253A%252F%252Fwww.myapp.com%26scope%3Demail

Example of response when the user is authenticated:

< HTTP/2 302 

< location: https://www.myapp.com#access_token=8abacc27-4eab-4c42-a30e-211d83063cbe&scope=email&iss=https%3A%2F%2Fwww.onewelcome.com%2Fauth%2Foauth2.0&token_type=Bearer&expires_in=3599&client_id=myoauth2client

How does OAuth 2.0 Resource Owner Password Credentials Grant (ROPC) works?

Resource Owner Password Credentials Grant (ROPC) requires users to provide their credentials (username and password) and because of this we recommend using this flow only when there is a high degree of trust between the resource owner and the client.

A step by step flow, can be seen below:

1. User is accessing your application and clicks login
2. User is presented with form for filling his/her credentials (username and password)
3. Authorization server validates the credentials, and issues an access token

What API do you need?

For ROPC grant you need the token endpoint, and specify in the request body that the request is a ROPC one by sending grant_type=password.

Example of request:

curl --request POST \

  --url https://www.onewelcome.com/onewelcome-dev/auth/oauth2.0/v1/token \

  --header 'Content-Type: application/x-www-form-urlencoded' \

  --data grant_type=password \

  --data username=myUsername \

  --data password=myPassword \

  --data scope=email \

  --data client_id=myoauth2client \

  --data client_secret=myoauth2clientPassword

Example of response:

{

  "access_token": "d5b8468a-e1da-4b8a-826f-0b6d96860b65",

  "refresh_token": "d052ddd3-bd54-4bb1-8d7e-30991a223685",

  "scope": "email",

  "token_type": "Bearer",

  "expires_in": 3599

}

How does Client Credentials Grant Works?

Client credentials is intended for server-side client applications, in which the client authenticates on behalf of itself.

As RFC6749 states, client credentials grant is used as an authorization grant typically when the client is acting on its own behalf (the client is also the resource owner) or is requesting access to protected resources based on an authorization previously arranged with the authorization server.

A step by step flow can be seen below:

1. Application sends a request to the authorization server, using it's own client_id and client_secret
2. Authorization server issues an access token which can be used to call different APIs

What APIs do you need?

For the Client Credentials Grant, as for the ROPC Grant, only the token endpoint is needed, with the difference that the value of grant_type has to be set to client_credentials.

An example of request can be seen below:

curl --request POST \

  --url https://www.onewelcome.com/onewelcome-dev/auth/oauth2.0/v1/token \

  --header 'Content-Type: application/x-www-form-urlencoded' \

  --data grant_type=client_credentials \

  --data client_id=myoauth2client \

  --data client_secret=myoauth2clientPassword \

  --data scope=read:users \

The response of this api call will look like below:

{

  "access_token": "9dd81f1c-4caa-40d3-a469-7897db220f22",

  "token_type": "Bearer",

  "expires_in": 3599,

  "scope": "read:users"

}

OIDC

OIDC is an extension of oauth2, and according to RFCit 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 an interoperable and REST-like manner.

The main difference between OAuth and OIDC is that OAuth is about authorization, and OIDC is about authentication. The definition of the authorization api that RFC 6749 specifies, states that for the attribute response_typethe possible values can be either token or code. OpenID adds a new value to the response type, which is id_tokenand allows to request in the response_type request parameter any combination of code, token and id_token.

Apart from the id_token response type, the specification also introduced a special value, none which is not allowed to be sent in any combination with the code, token and id_token.

As mentioned, the id_token contains informations about the authenticated user, and the properties added is referred to as claims. Not everything about the user is added in the id_token, but only informations that were requested using scopes.

If we take for example an authorize request with...&response_type=id_token&scope=openid email phone, this means that there should be an id token issued, and it should have the following information/claims about the user: email, email_verified,phone_number_verified, phone_number. This means that there is a one to many relationship between the requested scope and the number of claims/user attributes.

Why is an id_token useful?

Let's assume you have a regular web application that you register it with OneWelcome, and you want to configure it to allow user to login with Microsoft. Once the user logs in with Microsoft, an id_token will be generated and handed over to your application. Having the id_token you can show informations about the authenticated user, such as first name, last name and phone number, without any extra request, as it's the case with oauth2.

Example of request:

curl --request GET \

  --url 'https://www.onewelcome.com/onewelcome-dev/auth/oauth2.0/v1/authorize?response_type=token%20id_token&client_id=your_app&redirect_uri=http%3A%2F%2Fyour-app.com&scope=openid%20email%20phone&state=dssadas-e33adsdsadsad-wdwq3edas-dsa&nonce=aewqeqeewqweq'

Example of response:

< HTTP/2 302 

< location: http://your app.com#scope=email%20openid%20phone&state=something&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6IjM3TG1KRmk1aWNoa0RLZG81MlE4Rlc4TDFkMD0ifQ.eyJzdWIiOiJhMjZmNjc0ZS04YTg4LTQwZjgtYTZkZC1hMWE0YmJiN2M2ZGQiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImlzcyI6Imh0dHBzOi8vd3d3Lml3ZWxjb21lLmNvbS9hdXRoL29hdXRoMi4wIiwidG9rZW5OYW1lIjoiaWRfdG9rZW4iLCJwaG9uZV9udW1iZXJfdmVyaWZpZWQiOmZhbHNlLCJub25jZSI6ImFld3FlcWVld3F3ZXEiLCJhdWQiOiJ5b3VyX2FwcCIsImF6cCI6InlvdXJfYXBwIiwiYXV0aF90aW1lIjoxNjE4NTY4MzcwLCJwaG9uZV9udW1iZXIiOiIwMTM3MTIzNDU2Nzg5MGAiLCJleHAiOjE2MTg1NzE5NzYsInRva2VuVHlwZSI6IkpXVFRva2VuIiwiaWF0IjoxNjE4NTY4Mzc2LCJlbWFpbCI6Inh5ekB5b3BtYWlsLmNvbSIsInNlc3Npb24taWQiOiJlNTc2MjdlOC1hMTNhLTQ1MzgtYTFhYS0wY2UwYmRhMjYwMDkifQ.HKaRhlfaWapPxCFiIXG_bbt12KkMswxOi3j_6DTWQ5w

By decoding the JWT you can see details about the authenticated user, along with the standard claims defined by OpenID Connect Specification, the decoded JWT from the example above can be seen below:

{

  "sub": "a26f674e-8a88-40f8-a6dd-a1a4bbb7c6dd",

  "email_verified": false,

  "iss": "https://www.onewelcome.com/auth/oauth2.0",

  "tokenName": "id_token",

  "phone_number_verified": false,

  "nonce": "aewqeqeewqweq",

  "aud": "your_app",

  "azp": "your_app",

  "auth_time": 1618568370,

  "phone_number": "01371234567890`",

  "exp": 1618571976,

  "tokenType": "JWTToken",

  "iat": 1618568376,

  "email": "xyz@yopmail.com",

  "session-id": "e57627e8-a13a-4538-a1aa-0ce0bda26009"

}

What is response type none?

When the response_typeis none nothing is issued by the authorization server. According to OAuth2 RFC, the purpose for this attribute is to enable use cases where a party requests the Authorization Server to register a grant of access to a Protected Resource on behalf of a Client but requires no access credentials to be returned to the Client at that time.

A scenario described by OAuth2 RFC describing the usage of this response type is when a user wishes to purchase an application from a market, and desires to authorize application installation and grant the application access to Protected Resources in a single step. However, since the user is not presently interacting with the (not yet active) application, it is not appropriate to return access credentials simultaneously in the authorization step.

This flow requires to use only authorization API, and an example of a request, can be seen below:

curl --request GET \

  --url 'https://www.onewelcome.com/onewelcome-dev/auth/oauth2.0/v1/authorize?response_type=none&scope=email&client_id=your_app&redirect_uri=http%3A%2F%2Fyour-app.com&state=AFDvsaERwd3ed&nonce=EWAFDCaweAScxz'

A successful response would look like below:

< HTTP/2 302 

< location:  https://www.your-app.com/?scope=email&iss=https%3A%2F%2Fwww.onewelcome.com%2Fauth%2Foauth2.0&state=AFDvsaERwd3ed&client_id=your_app