Quick start

Simple guide on setting up an OAuth 2 Client for the Humanode OAuth 2 Service.

Implementing OAuth 2 manually is not recommended due to protocol complexity and vast variety of libraries for many languages.

Understanding the OAuth 2 protocol can ease the developing process.

OAuth 2

Getting OAuth 2 Credentials

This process is also called Client Registration.

OAuth 2 Credentials can be obtained for different purposes and environments. For developing there are Humanode OAuth 2 Staging environment

Staging Environment

For going production with your project check Going production page

Going Production

Authorization Server data

All the needed data about Humanode Authorization Server can be obtained via

<Authorization Server URL>/.well-known/openid-configuration

as Humanode OAuth 2 Service supports OpenID Connect protocol. Read mode at OpenID Connect page

OpenID Connect

OAuth 2 Client settings

This Client is represents the registered OAuth 2 Client for a spesific app.

Credentials should be set according to the registered client, as well as authentication method.

Callback and response type should be selected from the set in the registered OAuth 2 Client.

Authorization request

The next step after setting up the client will be obtaining the authorization code. To do this, an authorization request should be constructed and sent.

In implicit flow Access Token will be granted instead of authorization code. See here about why it is not recommended:

OAuth 2 Client

A couple of things should be accounted when constructing the request body.

Generally, scope in the request should be a subset of those in the registered OAuth 2 Client.

Currently Humanode OAuth 2 Service supports only 'openid' scope.

State shall be at least 8 characters long.

Token exchange

Authorization code is a single-use piece of data that should be exchanged to JWT.

JWT can be used to authenticate client until it expires.

Verify the JWT

JWT is signed by the authorization server and should be verified by using JWKs.

JWKs are provided by the authorization server at

<Authorization Server URL>/.well-known/jwks.json

Validate the JWT

Certain fields in JWT shall be validated, such as:

• client_id;

• scp (scopes);

• scp (subject) - unique identificator of a resource owner;

• iss (token issuer) - authorization server URL;

• iat (issued at) - check that not in the future;

• exp (expiration time).