Skip to main content

OAuth 2.0 and OIDC for BlockID

OAuth 2.0 (Open Authorization) is an authorization protocol that allows one application to access resources hosted by another application on behalf of a user without needing to share the user's credentials. OAuth2 uses Access Tokens to represent the authorization to access resources on behalf of the end-user. BlockID uses the JSON Web Token (JWT) format for our Access Tokens.

OpenID Connect (OIDC) is an authentication protocol that enables applications to support authentication processes in a secure and standardized way. Applications using OpenID Connect rely on identity providers such as 1Kosmos to securely handle authentication requests and verify the identities of their users.

Prerequsites​

  • OIDC application details
  • Valid proof of authentication (JWT) access token

Parameters​

  • dns: tenant domain as shown in the dashboard
  • communityName: tenant community as shown in the dashboard
  • licenseKey: tenant license key as shown in the dashboard
  • proofOfAuthenticationJwt: JWT token
  • clientId: oauth2 client ID
  • clientSecret: oauth2 client secret
  • redirectUri: oauth2 redirect URL
  • responseType: set as code
  • grantType: set as authorization_code or refresh_token
  • refreshToken: oauth2 refresh token

Request Format​

tip

All requests are plug-and-play, not copy-paste. Please ensure that you are replacing the parameters in the request format below with the actual values

OAuth2 Authorization Code​

  • Set tenant info
const BIDOauth2 = require('blockid-nodejs-helpers/BIDOauth2');

let tenantInfo = {
  dns: "<tenant dns>",
  communityName: "<tenant community>",
  licenseKey: "<tenant license>"
}
  • Add oauth2 details and grant type
let proofOfAuthenticationJwt = "<JWT token>";
let clientId = "<client ID>";
let clientSecret = "<client secret>";
let redirectUri = "<redirect URL>"
let responseType = "code";
let grantType = "<grant type>";  // either "authorization_code" or "refresh_token"
  • Set scope
/* For an openid connect (oidc) flow, the scope is "openid email profile"

For an authorization code flow, the scope is "email profile" */

let scope = "<scope>";
  • Set state
// State is optional during an oauth2 authorization flow. There should be no nonce parameter for an oauth2 authorization (when not using oidc claim)

let state = null;
  • Request oauth2 authorization code
async function requestAuthorizationCode() {

  let authorizationCodeResponse = await BIDOauth2.requestAuthorizationCode(tenantInfo, proofOfAuthenticationJwt, clientId, responseType, scope, redirectUri, state, nonce);
  console.log("authorizationCodeResponse::::::", JSON.stringify(authorizationCodeResponse));
  return authorizationCodeResponse;
}

requestAuthorizationCode();

OAuth2 Token​

  • Set tenant info
const BIDOauth2 = require('blockid-nodejs-helpers/BIDOauth2');

let tenantInfo = {
  dns: "<tenant dns>",
  communityName: "<tenant community>",
  licenseKey: "<tenant license>"
}
  • Add oauth2 details and authorization code
let clientId = "<client ID>";
let clientSecret = "<client secret>";
let redirectUri = "<redirectUri>";
let grantType = "<grant type>";  // either "authorization_code" or "refresh_token" 
let url = "<url>";         

// If calling refresh_token declare here 
let refreshToken =  "<refreshToken>";
  • Request oauth2 token
async function requestToken(code, refreshToken) {
  let requestTokenResponse = await BIDOauth2.requestToken(tenantInfo, clientId, clientSecret, grantType, redirectUri, code, refreshToken);
  console.log("requestTokenResponse::::::", requestTokenResponse);
  return requestTokenResponse;
}

return requestTokenResponse;

Example Requests​

OAuth2 Authorization with OpenID Connect (OIDC)​

Here's an example request showing the flow for OAuth2 authorization with OpenID

const BIDOauth2 = require('blockid-nodejs-helpers/BIDOauth2');

let tenantInfo = {
  dns: "blockid-trial.1kosmos.net",
  communityName: "devx",
  licenseKey: "9b074532-845b-4c75-ba3e-2b89598ad405"
}

let proofOfAuthenticationJwt = "xxxxx"; // JWT Token
let clientId = "2ee529699faa2aaf3b24b6154bc0xxxx";
let clientSecret = "6db7c242fc4ef1f98bf45d9e3f44d5a980b5d03ac52530e85d5dfc866f07xxxx";
let redirectUri = "https://xxxxxx.xxx/xxxx";
let responseType = "code";
let grantType = "authorization_code"; 

// For "openid connect" the scope is "openid email profile"
let scope = "openid email profile";

// State and nonce are optional during an openid connect flow (when using openid scope)  
let state = null;
let nonce = null;

// Request oauth2 authorization code
async function requestAuthorizationCode() {

  let authorizationCodeResponse = await BIDOauth2.requestAuthorizationCode(tenantInfo, proofOfAuthenticationJwt, clientId, responseType, scope, redirectUri, state, nonce);
  console.log("authorizationCodeResponse::::::", JSON.stringify(authorizationCodeResponse));
  return authorizationCodeResponse;
}

// Call requestAuthorizationCode
requestAuthorizationCode();

OAuth2 Refresh Token with OpenID Connect (OIDC)​

const BIDOauth2 = require('blockid-nodejs-helpers/BIDOauth2');

let tenantInfo = {
  dns: "blockid-trial.1kosmos.net",
  communityName: "devx",
  licenseKey: "9b074532-845b-4c75-ba3e-2b8950000000"
}

let clientId = "2ee529699faa2aaf3b24b6154bc0xxxx";
let clientSecret = "6db7c242fc4ef1f98bf45d9e3f44d5a980b5d03ac52530e85d5dfc866f07xxxx";
let redirectUri = "https://xxxxxx.xxx/xxxx";
let grantType = "refresh_token";

// add refresh token 
let refreshToken = "78Bwl7_wLQy5jfsb4hqM7MWK8f5PJSAXNgGo0_xxxxx";


async function requestToken(code, refreshToken) {
  let requestTokenResponse = await BIDOauth2.requestToken(tenantInfo, clientId, clientSecret, grantType, redirectUri, code, refreshToken);
  console.log("requestTokenResponse::::::", requestTokenResponse);
  return requestTokenResponse;
}

// Call requestToken
requestToken(null, refreshToken);

OAuth2 Authorization​

const BIDOauth2 = require('blockid-nodejs-helpers/BIDOauth2');

let tenantInfo = {
  dns: "blockid-trial.1kosmos.net",
  communityName: "devx",
  licenseKey: "9b074532-845b-4c75-ba3e-2b89598ad405"
}

let proofOfAuthenticationJwt = "xxxxx"; // JWT Token
let clientId = "2ee529699faa2aaf3b24b6154bc0xxxx";
let clientSecret = "6db7c242fc4ef1f98bf45d9e3f44d5a980b5d03ac52530e85d5dfc866f07xxxx";
let redirectUri = "https://xxxxxx.xxx/xxxx";
let responseType = "code";
let grantType = "authorization_code"; 

// For "authorization code" (not using openid), the scope is "email profile"
let scope = "email profile";


// State is optional during an oauth2 authorization flow. There should be no nonce parameter for an oauth2 authorization (when not using oidc claim)
let state = null;

// Request oauth2 authorization code
async function requestToken(code, refreshToken) {
  let requestTokenResponse = await BIDOauth2.requestToken(tenantInfo, clientId, clientSecret, grantType, redirectUri, code, refreshToken);
  console.log("requestTokenResponse::::::", requestTokenResponse);
  return requestTokenResponse;
}

// Call requestAuthorizationCode
requestAuthorizationCode();

OAuth2 Token​

const BIDOauth2 = require('blockid-nodejs-helpers/BIDOauth2');

let tenantInfo = {
  dns: "blockid-trial.1kosmos.net",
  communityName: "devx",
  licenseKey: "9b074532-845b-4c75-ba3e-2b89598ad405"
}

let clientId = "2ee529699faa2aaf3b24b6154bc0xxxx";
let clientSecret = "6db7c242fc4ef1f98bf45d9e3f44d5a980b5d03ac52530e85d5dfc866f07xxxx";
let redirectUri = "https://xxxxxx.xxx/xxxx";
let grantType = "authorization_code";
let url = "{redirectUrl}?code=xxxxxx&state=xxxx%22";

// Request oauth2 token 
async function requestToken(code, refreshToken) {
  let requestTokenResponse = await BIDOauth2.requestToken(tenantInfo, clientId, clientSecret, grantType, redirectUri, code, refreshToken);
  console.log("requestTokenResponse::::::", requestTokenResponse);
  return requestTokenResponse;
}

let urlData = new URL(url);
let searchParams = new URLSearchParams(urlData.searchParams);
let code = searchParams.get("code");

// Call requestToken 
requestToken(code, null);

Server Responses​

tip

Responses include dummy data as an example of a typical response

OAuth2 Authorization Code​

{
  "statusCode": 200,
  "url": "https://blockid-trial.1kosmos.net/?code=_ADKdVxxx&state=isuhJrBteWRXoNxxx"
}

The server accepted the request and returned a valid URL containing the oauth2 authorization code and state.

OAuth2 Access Token with OpenID Connect​

{
  access_token: "hpJufMH9txiObwaoXVZ6ftcmoKVE34_ZJrGjWhXXXXX",
  id_token: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjVtbmhJbmVYN1dLdk81NEM2c1h5VzFaXzZEQUwtV1F1S2EzTUxEbEtPeEUifQ.eyJzdWIiOiJqZW5pc2giLCJ1c2VybmFtZSI6ImplbmlzaCIsImZpcnN0bmFtZSI6ImplbmlzaCIsImxhc3RuYW1lIjoicGF0ZWwiLCJlbWFpbCI6ImplbmlzaC5wYXRlbEAxa29zbW9zLmNvbSIsImF0X2hhc2giOiI4Y3BHWlVGSU9vV1N5MkpocEtyY2J3IiwiYXVkIjoiMmVlNTI5Njk5ZmFhMmFhZjNiMjRiNjE1NGJjMDU0NjgiLCJleHAiOjE2NzI5MTczODMsImlhdCI6MTY3MjkxMzc4MywiaXNzIjoiaHR0cHM6Ly9ibG9ja2lkLWRldi4xa29zbW9zLm5ldC9vYXV0aDIvY29tbXVuaXR5L2RldngifQ.QG1k04soewILKaQxEM1IC55G26KOdZIwAaABLUGH1d1b-T3q3ipGgSFIpUqEpPCGWHaJyW3ssxdVV3Xu4AmHNBT5Ju9I7XQcP9iseSDhcvIL9uT0bJuv-gjJ3_Qkq4ULP6zPFEi91omCDRwtVZzFRQXzSYlVKBMzyTf1IMAb5Ieo_-g0ZjKSP7KMkRi-Ygr_2NCD17qibLnkVRUU_U_DuK2F9o76hC-uXHc7ZybSTxw7LfrYDBJCwcoGhtlC3WKk59P-XxxfAlwC-EHVtVi7l8KzccTocZm2qXqYkJDAlxgegx0nVRK2UNQsQ-UAfKiytlpXFjUN3nym8IRgXXXXXX",
  expires_in: 84600,
  scope: "openid email profile",
  token_type: "Bearer",
  status: 200
}

The server accepted the request and returned a valid URL containing the OAuth2 access token and OpenID ID token .

OAuth2 Refresh Token with OpenID Connect​

{
  access_token: "DovIic5QfVwIB6fwE5pIVtoHoXkovtfLfYvn7OVXXXX",
  expires_in: 84600,
  id_token: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjVtbmhJbmVYN1dLdk81NEM2c1h5VzFaXzZEQUwtV1F1S2EzTUxEbEtPeEUifQ.eyJzdWIiOiJqZW5pc2giLCJ1c2VybmFtZSI6ImplbmlzaCIsImZpcnN0bmFtZSI6ImplbmlzaCIsImxhc3RuYW1lIjoicGF0ZWwiLCJlbWFpbCI6ImplbmlzaC5wYXRlbEAxa29zbW9zLmNvbSIsImF0X2hhc2giOiI4Y3BHWlVGSU9vV1N5MkpocEtyY2J3IiwiYXVkIjoiMmVlNTI5Njk5ZmFhMmFhZjNiMjRiNjE1NGJjMDU0NjgiLCJleHAiOjE2NzI5MTczODMsImlhdCI6MTY3MjkxMzc4MywiaXNzIjoiaHR0cHM6Ly9ibG9ja2lkLWRldi4xa29zbW9zLm5ldC9vYXV0aDIvY29tbXVuaXR5L2RldngifQ.QG1k04soewILKaQxEM1IC55G26KOdZIwAaABLUGH1d1b-T3q3ipGgSFIpUqEpPCGWHaJyW3ssxdVV3Xu4AmHNBT5Ju9I7XQcP9iseSDhcvIL9uT0bJuv-gjJ3_Qkq4ULP6zPFEi91omCDRwtVZzFRQXzSYlVKBMzyTf1IMAb5Ieo_-g0ZjKSP7KMkRi-Ygr_2NCD17qibLnkVRUU_U_DuK2F9o76hC-uXHc7ZybSTxw7LfrYDBJCwcoGhtlC3WKk59P-XxxfAlwC-EHVtVi7l8KzccTocZm2qXqYkJDAlxgegx0nVRK2UNQsQ-UAfKiytlpXFjUN3nym8IRgXXXXXX",
  refresh_token: "t9l9PmQvC_uY5v-4R7cEVN7S8nlIItDue-zUCjXXXXX",
  scope: "openid email profile",
  token_type: "Bearer",
  status: 200
}

The server accepted the request and returned the refresh token and ID token.

OAuth2 Access Token​

{
  access_token: "hpJufMH9txiObwaoXVZ6ftcmoKVE34_ZJrGjWhXXXXX",
  expires_in: 86400,
  scope: "email profile",
  token_type: "Bearer",
  status: 200
}

The server accepted the request and returned a valid OAuth2 access token.