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=code to enable 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

javascript (fetch)

python

ruby

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 Implicit grant which attaches user pool tokens (id_token, access_token, expires_in and token_type) to the redirect_uri once the user is verified. The id_token can then be used by the Single Sign On server as authentication for license user in Activate License (Online Method).

If you do not want to expose user tokens or the redirect URI is too long for your use case, you can use the Authorization Code grant. In that case the code query parameter is attached to the redirect_uri (instead of id_token) and this code is sent in the request body when doing license activation. To enable Authorization Code grant add response_type=code to this endpoint. Example: /api/v4/sso_url/?customer_account_code=test&product=test&response_type=code

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