Identity Provider APIs

1. Overview

An Identity Provider is a named object that provides configuration to describe a federated identity provider. This configuration will be used to perform federated login using Passport.

2. Create an Identity Provider

Available Since Version 1.16.0

2.1. Request

Create an Identity Provider with a randomly generated Id

URI

POST /api/identity-provider

Create an Identity Provider with the provided unique Id

URI

POST /api/identity-provider/{identityProviderId}

Table 1. Request Parameters

identityProviderId [UUID] Optional defaults to secure random UUID

The Id to use for the new Identity Provider. If not specified a secure random UUID will be generated.

Table 2. Request Body

identityProvider.claimMap [Map<String, String>] Optional

A map of incoming claims to User fields, User data or Registration data. The key of the map is the incoming claim name from the configured identity provider. The following are allowed values:

  • birthDate

  • firstName

  • lastName

  • fullName

  • middleName

  • mobilePhone

  • imageUrl

  • timezone

  • UserData

  • RegistrationData

identityProvider.domains [Array<String>] Optional

An array of domains that are managed by this Identity Provider.

identityProvider.headerKeyParameter [String] Required

The name header claim that identifies the public key used to verify the signature. In most cases this be kid or x5t.

identityProvider.keys [Map<String, String>] Optional

A map of public keys used to verify JWT signatures issued from the configured Identity Provider. The key is the key identifier, this may be referred to as the kid or for X.509 certificates the x5t claim may be used.

The map may contain one entry with an empty map key. When provided this key will be used when no header claim is provided to indicate which public key should be used to verify the signature. Generally speaking this will only be used when the Identity Provider issues JWTs without a key identifier in the header.

identityProvider.name [String] Required

The name of the Identity Provider.

identityProvider.oauth2.authorization_endpoint [String] Optional

The authorization endpoint for this Identity Provider. This value is not utilized by Passport is only provided to be returned by the Lookup Identity Provider API response. During integration you may then utilize this value to perform the browser redirect to the OAuth2 authorize endpoint.

identityProvider.oauth2.token_endpoint [String] Optional

The token endpoint for this Identity Provider. This value is not utilized by Passport is only provided to be returned by the Lookup Identity Provider API response. During integration you may then utilize this value to complete the OAuth2 grant workflow.

identityProvider.uniqueIdentityClaim [String] Required

The name of the claim that represents the unique identify of the User. This will generally be email or the name of the claim that provides the email address.

identityProvider.uniqueIdentityClaimType [String] Required

The type of value represented by the claim identified by uniqueIdentityClaim. The possible values are:

  • Email - The unique claim is an email address.

  • Username - The unique claim is a username.

Example Request JSON
{
  "identityProvider": {
    "claimMap": {
      "first_name": "firstName",
      "last_name": "lastName",
      "dept": "RegistrationData"
    },
    "domains": [
      "acme.com",
      "acme.org"
    ],
    "headerKeyParameter" : "kid",
    "name": "Acme Corp. ADFS",
    "oauth2" : {
      "authorization_endpoint" : "https://acme.com/adfs/oauth2/authorize?client_id=cf3b00da-9551-460a-ad18-33232e6cbff0&response_type=code&redirect_uri=https://acme.com/oauth2/redirect",
      "token_endpoint" : "https://acme.com/adfs/oauth2/token"
    },
    "uniqueIdentityClaim": "email",
    "uniqueIdentityClaimType": "Email"
  }
}

2.2. Response

The response for this API contains the Identity Provider that was created.

Table 3. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

Table 4. Response Body for a single Identity Provider

identityProvider.claimMap [Map<String, String>]

A map of incoming claims to User fields, User data or Registration data. The key of the map is the incoming claim name from the configured identity provider. The following are allowed values:

  • birthDate

  • firstName

  • lastName

  • fullName

  • middleName

  • mobilePhone

  • imageUrl

  • timezone

  • UserData

  • RegistrationData

identityProvider.domains [Array<String>]

An array of domains that are managed by this Identity Provider.

identityProvider.headerKeyParameter [String]

The name header claim that identifies the public key used to verify the signature. In most cases this be kid or x5t.

identityProvider.keys [Map<String, String>]

A map of public keys used to verify JWT signatures issued from the configured Identity Provider. The key is the key identifier, this may be referred to as the kid or for X.509 certificates the x5t claim may be used.

The map may contain one entry with an empty map key. When provided this key will be used when no header claim is provided to indicate which public key should be used to verify the signature. Generally speaking this will only be used when the Identity Provider issues JWTs without a key identifier in the header.

identityProvider.id [UUID]

The unique Id of the Identity Provider.

identityProvider.name [String]

The name of the Identity Provider.

identityProvider.oauth2.authorization_endpoint [String]

The authorization endpoint for this Identity Provider. This value is not utilized by Passport is only provided to be returned by the Lookup Identity Provider API response. During integration you may then utilize this value to perform the browser redirect to the OAuth2 authorize endpoint.

identityProvider.oauth2.token_endpoint [String]

The token endpoint for this Identity Provider. This value is not utilized by Passport is only provided to be returned by the Lookup Identity Provider API response. During integration you may then utilize this value to complete the OAuth2 grant workflow.

identityProvider.uniqueIdentityClaim [String]

The name of the claim that represents the unique identify of the User. This will generally be email or the name of the claim that provides the email address.

identityProvider.uniqueIdentityClaimType [String]

The type of value represented by the claim identified by uniqueIdentityClaim. The possible values are:

  • Email - The unique claim is an email address.

  • Username - The unique claim is a username.

Example Response JSON
{
  "identityProvider": {
    "claimMap": {
      "first_name": "firstName",
      "last_name": "lastName",
      "dept": "RegistrationData"
    },
    "domains": [
      "acme.com",
      "acme.org"
    ],
    "headerKeyParameter" : "kid",
    "id" : "a4e78daa-33a6-4844-b081-7779af1f09a4",
    "name": "Acme Corp. ADFS",
    "oauth2" : {
      "authorization_endpoint" : "https://acme.com/adfs/oauth2/authorize?client_id=cf3b00da-9551-460a-ad18-33232e6cbff0&response_type=code&redirect_uri=https://acme.com/oauth2/redirect",
      "token_endpoint" : "https://acme.com/adfs/oauth2/token"
    },
    "uniqueIdentityClaim": "email",
    "uniqueIdentityClaimType": "Email"
  }
}

3. Retrieve an Identity Provider

Available Since Version 1.16.0

3.1. Request

Retrieve all of the Identity Providers

URI

GET /api/identity-provider

Retrieve an Identity Provider by Id

URI

GET /api/identity-provider/{identityProviderId}

Table 5. Request Parameters

identityProviderId [UUID] Required

The unique Id of the Identity Provider to retrieve.

3.2. Response

Table 6. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

404

The object you requested doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

Table 7. Response Body for a single Identity Provider

identityProvider.claimMap [Map<String, String>]

A map of incoming claims to User fields, User data or Registration data. The key of the map is the incoming claim name from the configured identity provider. The following are allowed values:

  • birthDate

  • firstName

  • lastName

  • fullName

  • middleName

  • mobilePhone

  • imageUrl

  • timezone

  • UserData

  • RegistrationData

identityProvider.domains [Array<String>]

An array of domains that are managed by this Identity Provider.

identityProvider.headerKeyParameter [String]

The name header claim that identifies the public key used to verify the signature. In most cases this be kid or x5t.

identityProvider.keys [Map<String, String>]

A map of public keys used to verify JWT signatures issued from the configured Identity Provider. The key is the key identifier, this may be referred to as the kid or for X.509 certificates the x5t claim may be used.

The map may contain one entry with an empty map key. When provided this key will be used when no header claim is provided to indicate which public key should be used to verify the signature. Generally speaking this will only be used when the Identity Provider issues JWTs without a key identifier in the header.

identityProvider.id [UUID]

The unique Id of the Identity Provider.

identityProvider.name [String]

The name of the Identity Provider.

identityProvider.oauth2.authorization_endpoint [String]

The authorization endpoint for this Identity Provider. This value is not utilized by Passport is only provided to be returned by the Lookup Identity Provider API response. During integration you may then utilize this value to perform the browser redirect to the OAuth2 authorize endpoint.

identityProvider.oauth2.token_endpoint [String]

The token endpoint for this Identity Provider. This value is not utilized by Passport is only provided to be returned by the Lookup Identity Provider API response. During integration you may then utilize this value to complete the OAuth2 grant workflow.

identityProvider.uniqueIdentityClaim [String]

The name of the claim that represents the unique identify of the User. This will generally be email or the name of the claim that provides the email address.

identityProvider.uniqueIdentityClaimType [String]

The type of value represented by the claim identified by uniqueIdentityClaim. The possible values are:

  • Email - The unique claim is an email address.

  • Username - The unique claim is a username.

Example Response JSON
{
  "identityProvider": {
    "claimMap": {
      "first_name": "firstName",
      "last_name": "lastName",
      "dept": "RegistrationData"
    },
    "domains": [
      "acme.com",
      "acme.org"
    ],
    "headerKeyParameter" : "kid",
    "id" : "a4e78daa-33a6-4844-b081-7779af1f09a4",
    "name": "Acme Corp. ADFS",
    "oauth2" : {
      "authorization_endpoint" : "https://acme.com/adfs/oauth2/authorize?client_id=cf3b00da-9551-460a-ad18-33232e6cbff0&response_type=code&redirect_uri=https://acme.com/oauth2/redirect",
      "token_endpoint" : "https://acme.com/adfs/oauth2/token"
    },
    "uniqueIdentityClaim": "email",
    "uniqueIdentityClaimType": "Email"
  }
}
Table 8. Response Body for all Identity Providers

identityProviders [Array]

The list of Identity Provider objects.

identityProviders[x].claimMap [Map<String, String>]

A map of incoming claims to User fields, User data or Registration data. The key of the map is the incoming claim name from the configured identity provider. The following are allowed values:

  • birthDate

  • firstName

  • lastName

  • fullName

  • middleName

  • mobilePhone

  • imageUrl

  • timezone

  • UserData

  • RegistrationData

identityProviders[x].domains [Array<String>]

An array of domains that are managed by this Identity Provider.

identityProviders[x].headerKeyParameter [String]

The name header claim that identifies the public key used to verify the signature. In most cases this be kid or x5t.

identityProviders[x].keys [Map<String, String>]

A map of public keys used to verify JWT signatures issued from the configured Identity Provider. The key is the key identifier, this may be referred to as the kid or for X.509 certificates the x5t claim may be used.

The map may contain one entry with an empty map key. When provided this key will be used when no header claim is provided to indicate which public key should be used to verify the signature. Generally speaking this will only be used when the Identity Provider issues JWTs without a key identifier in the header.

identityProviders[x].id [UUID]

The unique Id of the Identity Provider.

identityProviders[x].name [String]

The name of the Identity Provider.

identityProviders[x].oauth2.authorization_endpoint [String]

The authorization endpoint for this Identity Provider. This value is not utilized by Passport is only provided to be returned by the Lookup Identity Provider API response. During integration you may then utilize this value to perform the browser redirect to the OAuth2 authorize endpoint.

identityProviders[x].oauth2.token_endpoint [String]

The token endpoint for this Identity Provider. This value is not utilized by Passport is only provided to be returned by the Lookup Identity Provider API response. During integration you may then utilize this value to complete the OAuth2 grant workflow.

identityProviders[x].uniqueIdentityClaim [String]

The name of the claim that represents the unique identify of the User. This will generally be email or the name of the claim that provides the email address.

identityProviders[x].uniqueIdentityClaimType [String]

The type of value represented by the claim identified by uniqueIdentityClaim. The possible values are:

  • Email - The unique claim is an email address.

  • Username - The unique claim is a username.

Example Response JSON
{
  "identityProviders": [{
      "claimMap": {
        "first_name": "firstName",
        "last_name": "lastName",
        "dept": "RegistrationData"
      },
      "domains": [
        "acme.com",
        "acme.org"
      ],
      "headerKeyParameter" : "kid",
      "id" : "a4e78daa-33a6-4844-b081-7779af1f09a4",
      "name": "Acme Corp. ADFS",
      "oauth2" : {
        "authorization_endpoint" : "https://acme.com/adfs/oauth2/authorize?client_id=cf3b00da-9551-460a-ad18-33232e6cbff0&response_type=code&redirect_uri=https://acme.com/oauth2/redirect",
        "token_endpoint" : "https://acme.com/adfs/oauth2/token"
      },
      "uniqueIdentityClaim": "email",
      "uniqueIdentityClaimType": "Email"
    }]
}

4. Update an Identity Provider

Available Since Version 1.16.0

4.1. Request

Update an Identity Provider

URI

PUT /api/identity-provider/{identityProviderId}

Table 9. Request Parameters

identityProviderId [UUID] Required

The unique Id of the Identity Provider to update.

Table 10. Request Body

identityProvider.claimMap [Map<String, String>] Optional

A map of incoming claims to User fields, User data or Registration data. The key of the map is the incoming claim name from the configured identity provider. The following are allowed values:

  • birthDate

  • firstName

  • lastName

  • fullName

  • middleName

  • mobilePhone

  • imageUrl

  • timezone

  • UserData

  • RegistrationData

identityProvider.domains [Array<String>] Optional

An array of domains that are managed by this Identity Provider.

identityProvider.headerKeyParameter [String] Required

The name header claim that identifies the public key used to verify the signature. In most cases this be kid or x5t.

identityProvider.keys [Map<String, String>] Optional

A map of public keys used to verify JWT signatures issued from the configured Identity Provider. The key is the key identifier, this may be referred to as the kid or for X.509 certificates the x5t claim may be used.

The map may contain one entry with an empty map key. When provided this key will be used when no header claim is provided to indicate which public key should be used to verify the signature. Generally speaking this will only be used when the Identity Provider issues JWTs without a key identifier in the header.

identityProvider.name [String] Required

The name of the Identity Provider.

identityProvider.oauth2.authorization_endpoint [String] Optional

The authorization endpoint for this Identity Provider. This value is not utilized by Passport is only provided to be returned by the Lookup Identity Provider API response. During integration you may then utilize this value to perform the browser redirect to the OAuth2 authorize endpoint.

identityProvider.oauth2.token_endpoint [String] Optional

The token endpoint for this Identity Provider. This value is not utilized by Passport is only provided to be returned by the Lookup Identity Provider API response. During integration you may then utilize this value to complete the OAuth2 grant workflow.

identityProvider.uniqueIdentityClaim [String] Required

The name of the claim that represents the unique identify of the User. This will generally be email or the name of the claim that provides the email address.

identityProvider.uniqueIdentityClaimType [String] Required

The type of value represented by the claim identified by uniqueIdentityClaim. The possible values are:

  • Email - The unique claim is an email address.

  • Username - The unique claim is a username.

Example Request JSON
{
  "identityProvider": {
    "claimMap": {
      "first_name": "firstName",
      "last_name": "lastName",
      "dept": "RegistrationData"
    },
    "domains": [
      "acme.com",
      "acme.org"
    ],
    "headerKeyParameter" : "kid",
    "name": "Acme Corp. ADFS",
    "oauth2" : {
      "authorization_endpoint" : "https://acme.com/adfs/oauth2/authorize?client_id=cf3b00da-9551-460a-ad18-33232e6cbff0&response_type=code&redirect_uri=https://acme.com/oauth2/redirect",
      "token_endpoint" : "https://acme.com/adfs/oauth2/token"
    },
    "uniqueIdentityClaim": "email",
    "uniqueIdentityClaimType": "Email"
  }
}

4.2. Response

The response for this API contains the Identity Provider that was updated.

Table 11. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

404

The object you are trying to updated doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

Table 12. Response Body

identityProvider.claimMap [Map<String, String>]

A map of incoming claims to User fields, User data or Registration data. The key of the map is the incoming claim name from the configured identity provider. The following are allowed values:

  • birthDate

  • firstName

  • lastName

  • fullName

  • middleName

  • mobilePhone

  • imageUrl

  • timezone

  • UserData

  • RegistrationData

identityProvider.domains [Array<String>]

An array of domains that are managed by this Identity Provider.

identityProvider.headerKeyParameter [String]

The name header claim that identifies the public key used to verify the signature. In most cases this be kid or x5t.

identityProvider.keys [Map<String, String>]

A map of public keys used to verify JWT signatures issued from the configured Identity Provider. The key is the key identifier, this may be referred to as the kid or for X.509 certificates the x5t claim may be used.

The map may contain one entry with an empty map key. When provided this key will be used when no header claim is provided to indicate which public key should be used to verify the signature. Generally speaking this will only be used when the Identity Provider issues JWTs without a key identifier in the header.

identityProvider.id [UUID]

The unique Id of the Identity Provider.

identityProvider.name [String]

The name of the Identity Provider.

identityProvider.oauth2.authorization_endpoint [String]

The authorization endpoint for this Identity Provider. This value is not utilized by Passport is only provided to be returned by the Lookup Identity Provider API response. During integration you may then utilize this value to perform the browser redirect to the OAuth2 authorize endpoint.

identityProvider.oauth2.token_endpoint [String]

The token endpoint for this Identity Provider. This value is not utilized by Passport is only provided to be returned by the Lookup Identity Provider API response. During integration you may then utilize this value to complete the OAuth2 grant workflow.

identityProvider.uniqueIdentityClaim [String]

The name of the claim that represents the unique identify of the User. This will generally be email or the name of the claim that provides the email address.

identityProvider.uniqueIdentityClaimType [String]

The type of value represented by the claim identified by uniqueIdentityClaim. The possible values are:

  • Email - The unique claim is an email address.

  • Username - The unique claim is a username.

Example Response JSON
{
  "identityProvider": {
    "claimMap": {
      "first_name": "firstName",
      "last_name": "lastName",
      "dept": "RegistrationData"
    },
    "domains": [
      "acme.com",
      "acme.org"
    ],
    "headerKeyParameter" : "kid",
    "id" : "a4e78daa-33a6-4844-b081-7779af1f09a4",
    "name": "Acme Corp. ADFS",
    "oauth2" : {
      "authorization_endpoint" : "https://acme.com/adfs/oauth2/authorize?client_id=cf3b00da-9551-460a-ad18-33232e6cbff0&response_type=code&redirect_uri=https://acme.com/oauth2/redirect",
      "token_endpoint" : "https://acme.com/adfs/oauth2/token"
    },
    "uniqueIdentityClaim": "email",
    "uniqueIdentityClaimType": "Email"
  }
}

5. Delete an Identity Provider

Available Since Version 1.16.0

5.1. Request

Delete an Identity Provider by Id

URI

DELETE /api/identity-provider/{identityProviderId}

Table 13. Request Parameters

identityProviderId [UUID] Required

The unique Id of the Identity Provider to delete.

5.2. Response

This API does not return a JSON response body.

Table 14. Response Codes
Code Description

200

The request was successful. The response will be empty.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

404

The object you are trying to delete doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

5.3. Lookup an Identity Provider

The Lookup API is intended to be used during a federated login workflow. For example, during a login you may collect the user’s email address, that address or domain can be sent on the request to lookup which Identity Provider is managing the domain.

Available Since Version 1.16.0

5.4. Request

Lookup an Identity Provider by managed domain

URI

GET /api/identity-provider/lookup?domain={domain}

Table 15. Request Parameters

domain [String] Required

The email domain or the full email address of the user.

For example, jenny@acme.com and acme.com are functionally equivalent.

5.5. Response

The Lookup response is a subset of the Identity Provider configuration that would be returned by the Retrieve an Identity Provider. A 200 response code indicates the domain is managed and the response will contain a JSON body, a 404 response code indicates it is not managed by a configured Identity Provider.

Table 16. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

404

The object you requested doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

Table 17. Example Response JSON

identityProvider.id [UUID]

The unique Id of the Identity Provider.

identityProvider.name [String]

The name of the Identity Provider.

identityProvider.oauth2.authorization_endpoint [String]

The OAuth2 Authorize endpoint. This may be used to as the redirect location to begin the authorize workflow so that it does not need to be hard coded in your application.

identityProvider.oauth2.token_endpoint [String]

The OAuth2 Token endpoint. This may be used during your integration so that this URI does not need to be hard coded in your application.

Example Response JSON
{
  "identityProvider" : {
    "id" : "a4e78daa-33a6-4844-b081-7779af1f09a4",
    "name" : "Acme Corp. ADFS",
    "oauth2" : {
      "authorization_endpoint" : "https://acme.com/adfs/oauth2/authorize?client_id=cf3b00da-9551-460a-ad18-33232e6cbff0&response_type=code&redirect_uri=https://acme.com/oauth2/redirect",
      "token_endpoint" : "https://acme.com/adfs/oauth2/token"
    }
  }
}