1. Home >
2. API >
3. 2 >
4. API Authorization >
5. API Authorization Management

API Authorization Management

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

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.

For more information about API authorization, see How to setup an API Authorization PoC.

{
  "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

Clicking Run in Postman button navigates to the page where you can fork the collection to your workspace. Forking the collection into your workspace will enable you to contribute to the source collection using pull requests. You can also view the collection in a public workspace if you like and even import a copy of the collection using the links present on the screen.

---