Single Sign On URL

Learn how to generate a URL for the hosted UI used for Single Sign On (SSO) of license users with the /api/v4/sso_url endpoint.

---

Endpoint

• Method: GET
• Path: /api/v4/sso_url
• Description: Returns the Single Sign-On URL for license user authorization.

Authentication

See License API Authorization.

Required headers

• Date (string)
• Authorization (string)

Recommended headers

• Accept: application/json

Request

Query parameters

Required:

• product (string)
• customer_account_code (string)

Optional:

• response_type (string) — code or token. Default: code

Example request URL: /api/v4/sso_url?product=string&customer_account_code=string (You can add &response_type=token to enable Implicit grant, otherwise it will default to the Authorization Code grant)

Examples

curl

curl --location --request GET '/api/v4/sso_url?product=string&customer_account_code=string' \
--header 'Accept: application/json' \
--header 'Date: string' \
--header 'Authorization: string'

nodejs

var request = require('request');
var options = {
  method: 'GET',
  url: '/api/v4/sso_url?product=string&customer_account_code=string',
  headers: {
    'Accept': 'application/json',
    'Date': 'string',
    'Authorization': 'string'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

javascript (fetch)

var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Date", "string");
myHeaders.append("Authorization", "string");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("/api/v4/sso_url?product=string&customer_account_code=string", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

python

import requests

url = "/api/v4/sso_url?product=string&customer_account_code=string"

headers = {
  "Accept": "application/json",
  "Date": "string",
  "Authorization": "string"
}

response = requests.get(url, headers=headers)
print(response.text)

ruby

require "uri"
require "net/http"

url = URI("/api/v4/sso_url?product=string&customer_account_code=string")

http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Accept"] = "application/json"
request["Date"] = "string"
request["Authorization"] = "string"

response = http.request(request)
puts response.read_body

Example success response (200)

{
  "url": "https://auth.licensespring.com/realms/user-portal/protocol/openid-connect/auth?scope=openid&response_type=code&client_id=license-users&redirect_uri=http://localhost&kc_idp_hint=foo-bar",
  "openid_configuration": {
    "issuer": "https://auth.licensespring.com/realms/user-portal",
    "end_session_endpoint": "https://auth.licensespring.com/realms/user-portal/protocol/openid-connect/logout",
    "token_endpoint": "https://auth.licensespring.com/realms/user-portal/protocol/openid-connect/token",
    "introspection_endpoint": "https://auth.licensespring.com/realms/user-portal/protocol/openid-connect/token/introspect"
  }
}

Authorization method

By default, authorization for SSO uses the Authorization Code grant which attaches a code query parameter to the redirect_uri once the user is verified. This code is then sent in the request body when doing license activation.

If you prefer to receive user pool tokens directly on the redirect, you can use the Implicit grant. In that case, user pool tokens (id_token, access_token, expires_in, and token_type) are attached to the redirect_uri (instead of code) once the user is verified, and the access_token can then be used for license activation. Be aware that this exposes user tokens in the redirect URI and results in a longer URI. To enable Implicit grant, add response_type=token to this endpoint. Example: /api/v4/sso_url/?customer_account_code=test&product=test&response_type=token

Schema

Request + response schema (TypeScript + JSON Schema)

Request Query Parameters (TypeScript)

type SSOURLRequestParams = {
  product: string,
  customer_account_code: string,
  response_type?: 'code' | 'token' | undefined
}

Request Query Parameters (JSON Schema)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "product": { "type": "string" },
    "customer_account_code": { "type": "string" },
    "response_type": { "type": "string", "enum": ["code", "token"] }
  },
  "required": ["product", "customer_account_code"],
  "additionalProperties": false
}

Response body + response body schema (TypeScript + JSON Schema)

Response Body (TypeScript)

type SSOURLResponseBody = {
  url: string,
  openid_configuration: {
    issuer: string,
    end_session_endpoint: string,
    token_endpoint: string,
    introspection_endpoint: string,
  }
}

Response Body (JSON Schema)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": { "type": "string" },
    "openid_configuration": {
      "type": "object",
      "properties": {
        "issuer": { "type": "string" },
        "end_session_endpoint": { "type": "string" },
        "token_endpoint": { "type": "string" },
        "introspection_endpoint": { "type": "string" }
      }
    }
  },
  "required": ["url"],
  "additionalProperties": false
}

Errors

If an error occurs, the response will have an HTTP status code >= 400 and the response body will contain an error description in this format:

{
  status: number,
  code: string,
  message: string
}

Error schema (JSON Schema)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": { "type": "number" },
    "code": { "type": "string" },
    "message": { "type": "string" }
  },
  "required": [
    "status",
    "code",
    "message"
  ],
  "additionalProperties": false
}

List of exceptions

unknown_product (400): Provided product was not found

missing_headers (400): Some headers are missing

authorization_missing_params (400): Some parameters are missing in the authorization: { params }