This document serves as a technical overview document of the requirements involved in setting up Logixboard Single Sign-On (SSO), specifically via OpenID Connect (OIDC). It further documents the per-user provisioning flow which happens over an out-of-band GraphQL endpoint.
It is assumed at this point that you have a user pool and a publicly-accessible OpenID Connect Identity Provider (hereon IdP) to expose said user pool.
Configuration Required By Logixboard SSO
Logixboard SSO will require you to configure an application in your IdP. For this, we will provide you with a Callback URL. You will need to create the application using this value, and ensure that you grant the application the following OAuth scopes (all are required):
openidemailprofile
Your IdP will provide you with a Client ID and a Client Secret, which need to be provided to your Logixboard representative for us to complete our half of SSO setup.
In addition, you will need to provide your Logixboard representative with the metadata discovery endpoint URL for your OIDC IdP. This will end with /.well-known/openid-configuration.
Associating Federated Users with CargoWise Organizations
Users must be mapped to a CargoWise organization in Logixboard. For the first organization mapping, which provisions the user for use in Logixboard, you'll need to use the Logixboard Public API over GraphQL, available at the following URLs, depending on the region in which your account is hosted:
Oregon, US 🇺🇸: https://api.internal.logixboard.com/api/v1/graphql
💡 Logixboard is strictly region-specific - an account that is hosted in Paris cannot be accessed using the Public API in Oregon, and vice-versa. Requests made to the wrong region will result in errors. If you aren't sure where your account is hosted, ask your Logixboard representative.
All Logixboard Public API calls are authenticated with a pre-shared key, which will be provided to you by your Logixboard representative when SSO is turned on for your account. They are passed in via the Authorization HTTP header using the custom PSK type, for example:
Authorization: PSK abcde12345abcde12345
💡 Do not use the Bearer authorization type despite the apparent similarity at first glance. Bearer is a well-defined term in IETF's
RFC 6750, and the Logixboard Public API does not use OAuth 2.0 Bearer Tokens for authentication. Implicitly, this means you must have access to the raw HTTP headers that are sent along with your request, as PSK is not a standardized Authorization type. Ensure your HTTP or GraphQL library exposes them. Requests sent with missing or malformed Authorization headers will be considered invalid and will not result in successful authentication.
User-Org associations are created using the following GraphQL mutation (using API v1). This mutation can be run before or after a user logs in for the first time, though if a user attempts to log in before they are provisioned, they will be presented with a waiting screen and a note to contact their administrator.
# given variables:
# {
# "input": {
# "email": "[email protected]",
# "name": "User's Full Name",
# "cw1OrganizationCode": "CW1ORGCODE"
# }
# }
mutation ProvisionSsoUser($input: ProvisionSsoUserInput!) {
provisionSsoUser(input: $input) {
clientMutationId
user {
name
id
}
}
}
Deprovisioning Users
Users are deprovisioned using the following GraphQL mutation. This mutation should be called every time a user is deprovisioned in your IdP.
# given variables:
# {
# "input": {
# "email": "[email protected]"
# }
# }
mutation DeprovisionSsoUser($input: DeprovisionSsoUserInput!) {
deprovisionSsoUser(input: $input) {
clientMutationId
}
}