See api-docs Menu

API Authorization Management

This collection of APIs lets you configure OneLogin as an Authorization Server.

Early Access Release

This API is currently in early preview release and may be subject to future breaking changes. If you’re interested in using this API please contact your account manager or our support team.

The purpose of the Authorization Server is to authenticate a user and return an Access Token for authorizing access to downstream APIs. These APIs could be self hosted or provided via an API gateway.

{
  "jti": "HlKVBL__W1pdAe0BOjwDe",
  "sub": "35666371",
  "iss": "https://subdomain.onelogin.com/oidc/2",
  "iat": 1573508187,
  "exp": 1573509087,
  "scope": "openid profile",
  "aud": [
    "http://example.com/contacts"
  ],
  "azp": "78d1d040-20c9-0136-5146-067351775fae92920"
}

You will find API endpoints for configuring the base endpoint of your API as well as defining scopes, claims and client apps.

Resource Identifier & Audience

Every API must have a unique identifier, this is known as the Resource Identifier.

In most cases the Audience will be the same as the Resource Identifier but it can also support multiple API endpoints. This is useful if you want to issue an Access Token that will be used against several different APIs.

For example

{
  "resource_identifier": "https://example.com",
  "audiences": [
    "https://example.com/contacts"
    "https://example.com/products"
    "https://another-api.com/orders"
  ]
}

Will be reflected in the Access Token like this

{
  "jti": "HlKVBL__W1pdAe0BOjwDe",
  "sub": "35666371",
  "iss": "https://subdomain.onelogin.com/oidc/2",
  "iat": 1573508187,
  "exp": 1573509087,
  "scope": "openid profile",
  "aud": [
    "https://example.com/contacts"
    "https://example.com/products"
    "https://another-api.com/orders"
  ],
  "azp": "78d1d040-20c9-0136-5146-067351775fae92920"
}

Scopes

Scopes can be used to represent actions or access levels within your API.

When a user is authenticated and an Access Token is issued the requested scopes will be included in the resulting Access Token. Your API or API gateway is then responsible for verifying that the Access Token contains the required scopes to perform the requested action.

For example, you might have a Contacts API that allows users to Create, Read, Update, & Delete contact records. These actions could be represented by the following scopes.

contacts:read
contacts:create
contacts:update
contacts:delete

If the authentication request only included contacts:read then the Access Token would be restricted to that scope.

{
  "jti": "HlKVBL__W1pdAe0BOjwDe",
  "sub": "35666371",
  "iss": "https://subdomain.onelogin.com/oidc/2",
  "iat": 1573508187,
  "exp": 1573509087,
  "scope": "openid profile contacts:read",
  "aud": [
    "https://example.com/contacts"
  ],
  "azp": "78d1d040-20c9-0136-5146-067351775fae92920"
}

Claims

Claims are attributes that exist in the Access Token. They are useful if you want to include some custom information in the Access Token. Claims can be mapped to any standard or custom user field.

For example, you may want to include an employee_id in the Access Token.

{
  "employee_id": "some-employee-value",
  "jti": "HlKVBL__W1pdAe0BOjwDe",
  "sub": "35666371",
  "iss": "https://subdomain.onelogin.com/oidc/2",
  "iat": 1573508187,
  "exp": 1573509087,
  "scope": "openid profile contacts:read",
  "aud": [
    "https://example.com/contacts"
  ],
  "azp": "78d1d040-20c9-0136-5146-067351775fae92920"
}

Client Apps

All requests to authorize access to an API must go through an OpenId Connect application. Therefore you need to assign at least one OpenId Connect application to your API Authorization configuration.

You can also limit the scopes that can be requested via a client app.

For example, you might have a customer facing mobile app and a backend administration app that are both accessing the same API.

The customer facing app could be restricted to using the read scope.

[
  {
    "name": "Mobile App",
    "api_auth_id": 1022697,
    "scopes": [
      {
        "description": "Read some contacts",
        "id": 25,
        "value": "contacts:read"
      }
    ],
    "app_id": 909021
  }
]

While the backend administration app might have access to all scopes.

[
  {
    "name": "Backend Admin App",
    "api_auth_id": 1022697,
    "scopes": [
      {
        "description": "Read some contacts",
        "id": 25,
        "value": "contacts:read"
      },
      {
        "description": "Create a contact",
        "id": 26,
        "value": "contacts:create"
      },
      {
        "description": "Update a contact",
        "id": 27,
        "value": "contacts:update"
      },
      {
        "description": "Delete a contact",
        "id": 28,
        "value": "contacts:delete"
      }
    ],
    "app_id": 909021
  },
]

When authenticating via OpenId Connect if a scope is requested that is not allowed for that app then the user will get an error.

Postman Collection

Replace sample variables indicated by {{ }} with your actual values.

Download for API Authorization Management


Have a Question?

Found a bug? Submit a support ticket.

Have a product idea or request? Share it with us in our Ideas Portal.