OpenID Connect (OIDC)

Devii supports authentication through OpenID Connect (OIDC) providers such as Google, AWS, Microsoft Entra ID, and others.

OIDC allows users to authenticate using an external identity provider rather than storing credentials directly in Devii. When configured, Devii verifies the identity token returned by the provider and maps the authenticated user to a Devii role using a configured comparison field.

Permissions

Access to configure OIDC objects is role-based. Only installation root roles (pxadmin) can create OIDC providers. Tenant root roles can create OIDC configurations. Role OIDC mappings (role_oidc) can be created by anyone with role creation privileges on behalf of others, and any user can create and update their own mappings.

SaaS vs. Hosted Deployments

SaaS users — Devii has a set of providers already configured. Query oidc_providers to see what is currently available. As a tenant admin, you only need to create your own OIDC configuration using a client_id and client_secret obtained by registering your application directly with your chosen provider. When registering, make sure your setup matches the comparison_field already configured for that provider in Devii — this can also be found by querying oidc_providers.

Hosted deployments — Providers are configured on a per-tenant basis by the pxadmin. If you are hosting multiple tenants under a single organization with centralized IT administration, tenants can share the same client_id and client_secret across configurations.

Configuration Overview

Setting up OIDC in Devii requires four steps, completed in order:

1. Register Devii as an application with your identity provider.
2. Create an OIDC provider in Devii using create_oidc_providers, pxadmin only.
3. Create an OIDC configuration in Devii using create_oidc_config.
4. Map a Devii role to the OIDC identity using create_role_oidc.

All three mutations are available under the roles_pbac GraphQL schema namespace. Each object also supports the standard update and delete mutations.

Register Devii with Your Identity Provider

Before configuring OIDC in Devii, setup is required on the identity provider side. This allows the provider to trust Devii as an authorized application.

The following example demonstrates setup using Microsoft Entra ID (Azure AD).

1. Navigate to Azure Portal → Azure Active Directory → App registrations.
2. Select New registration.
3. Configure the Authorized redirect URI to match the URI you will configure in Devii (for example: https://api.devii.io/oidc).
4. Record the Application (client) ID.
5. Create a Client Secret.

Store the client secret securely — it will be required when configuring OIDC in Devii and cannot be retrieved after creation.

Create an OIDC Provider (pxadmin only)

Create the OIDC provider record in Devii using the create_oidc_providers mutation.

mutation Create_oidc_providers ($i: oidc_providersInput) {
    create_oidc_providers(input: $i) {
        providerid
        name
        auth_uri
        token_uri
        jwks_uri
        comparison_field
    }
}

Variables:

{
    "i": {
        "name": "Microsoft Entra ID",
        "auth_uri": "https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize",
        "token_uri": "https://login.microsoftonline.com/organizations/oauth2/v2.0/token",
        "jwks_uri": "https://login.microsoftonline.com/organizations/discovery/v2.0/keys",
        "comparison_field": "oid"
    }
}

The response returns a providerid, which is required in the next step.

Provider Fields

• name: String (required) Descriptive name of the identity provider.
• auth_uri: String (required) Authorization endpoint used to authenticate the user with the provider.
• token_uri: String (required) Endpoint used to exchange the authorization code for an ID token.
• jwks_uri: String (required) URI that provides the provider's JSON Web Key Set (JWKS) used to verify token signatures.
• comparison_field: String (optional) Field from the OIDC id_token used to identify the user. Defaults to sub if omitted. Some providers expose alternate identifiers — for example, Microsoft Entra ID uses oid and Google supports email. Consult your provider's documentation to determine the appropriate value.

The value specified in comparison_field must correspond to a claim returned in the provider's ID token. Devii uses this value to match the authenticated identity to the sub_id configured in Step 4.

Create an OIDC Configuration

Create the OIDC configuration in Devii using the create_oidc_config mutation. This links your provider credentials to the provider record created in Step 2.

mutation Create_oidc_config ($i: oidc_configInput) {
    create_oidc_config(input: $i) {
        confid
        providerid
        client_id
        client_secret_uuid
        createtime
        client_secret
    }
}

Variables:

{
    "i": {
        "providerid": 1,
        "client_id": "xxxxxxxxxxxxxxxxxxxxxxxxxx",
        "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxx"
    }
}

The response returns a confid, which is required in Step 4.

Configuration Fields

• providerid: Int (required) The ID of the OIDC provider created in Step 2.
• client_id: String (required) Client ID obtained from the identity provider during app registration.
• client_secret: String (required) Client secret obtained from the identity provider during app registration. This value is not logged and is stored in encrypted storage.

Map a Role to the OIDC Identity

Before completing this step, locate the sub_id value for the user you want to authenticate. See Finding the Provider sub Value below.

Link a Devii role to an OIDC identity using the create_role_oidc mutation.

mutation Create_role_oidc ($i: role_oidcInput) {
    create_role_oidc(input: $i) {
        roleid
        confid
        sub_id
    }
}

Variables:

{
    "i": {
        "roleid": 1,
        "confid": 1,
        "sub_id": "e629a360-00a4-41ff-8b98-b0be00233e1a"
    }
}

Role Configuration Fields

• roleid: ID! (required) The Devii role to associate with the external identity, primary and foreign key.
• confid: ID! (required) The OIDC configuration created with create_oidc_config
• sub_id: String (required) The provider's external sub identifier for the user.

A role can have more than one role_oidc mapping — one per oidc_config in the tenant. This means if multiple providers are configured, a role can authenticate with any of them interchangeably.

The client_id and client_secret values are generated by the identity provider when registering the Devii application. These credentials allow Devii to exchange authorization codes for ID tokens during authentication.

Finding the Provider sub Value

The sub_id field in the role mapping must match the value of the configured comparison_field in the ID token returned by your identity provider for that user.

How you retrieve this value depends on your provider:

• Microsoft Entra ID (oid): Find the user's Object ID in Azure Portal → Azure Active Directory → Users → [select user] → Object ID.
• Google (sub or email): The sub is a stable numeric identifier visible in the Google People API or by decoding an ID token for that user. If using email, use the user's Google account email address.
• Okta / Auth0: Decode an ID token issued for the user (using a tool such as jwt.io) and copy the value of the sub claim.

To decode an ID token and inspect its claims manually:

# Paste the token into jwt.io, or decode with bash:
echo "" | base64 --decode

The claim name to look for is whatever you configured as comparison_field when creating the provider.

Retrieving a Devii Access Token

Once the provider, configuration, and role mapping are in place, your application initiates authentication by calling the /oidc endpoint. Devii redirects the user to the identity provider's login page. After the user authenticates, the provider redirects back to Devii with an authorization code, which Devii exchanges for an ID token and verifies against the configured sub_id.

Authentication Flow

User → Your App → POST /oidc → Devii → Identity Provider (login)
                                       ↓
                             Devii ← Authorization Code
                                       ↓
                        Token exchange & sub_id verification
                                       ↓
                      Devii Access Token returned to Your App

Example Request

curl -X POST https://api.devii.io/oidc \
  -H "Content-Type: application/json" \
  -d '{
      "tenantid": 1,
      "roleid": 2051,
      "confid": 1
  }'

Request Fields

• tenantid: Int (required) The Devii tenant where authentication is being performed.
• roleid: ID! (required) The Devii role associated with the configured OIDC identity.
• confid: ID! (required) The OIDC configuration ID created in Step 3.

If authentication succeeds and the identity matches the configured sub_id, Devii returns an access token for the specified role. This token can then be used in the Authorization header when making requests to the Devii GraphQL API.

---

Common OIDC Providers​

The following resources link to official documentation for setting up commonly used identity providers with OIDC. Each provider has its own registration and configuration process — complete that setup before configuring the provider in Devii.

Understanding OIDC​

OpenID Connect Protocol & How It Works Official overview and explanation of the OIDC protocol from the OpenID Foundation.

• https://openid.net/developers/how-connect-works/

Provider Documentation​

Google (OpenID Connect / Sign-in with Google) Google's official developer guide to using OAuth 2.0 and OpenID Connect for authentication and getting ID tokens.

• https://developers.google.com/identity/openid-connect/openid-connect

Facebook Login & OIDC Configuration Official Facebook documentation for setting up authentication via OAuth 2.0 / OIDC token flows. Not purely labeled "OIDC," but Facebook's login system issues OIDC-compatible tokens once configured.

• https://developers.facebook.com/docs/facebook-login/

AWS

• OpenID Connect (OIDC) Identity Provider in AWS IAM — Official guide for adding an external OIDC IdP into IAM for trust and federation.
  • https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html
• Social & OIDC Providers with Amazon Cognito — Shows how to link providers like Google and Facebook to Cognito using OIDC and social login.
  • https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-social-idp.html

Microsoft Entra ID (Azure AD)

• Microsoft Identity Platform – OIDC Protocol Guide — Microsoft's official documentation explaining how to use OIDC with Entra ID (formerly Azure AD).
  • https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc
• Set up OIDC Identity Provider with Entra ID — App registration and configuration guide.
  • https://learn.microsoft.com/en-us/power-pages/security/authentication/openid-settings

Keycloak

• Keycloak is an open-source identity provider that organizations self-host on their own infrastructure. Endpoint URLs vary based on your installation domain and realm name. See the official documentation to locate your realm's endpoints.
  • https://www.keycloak.org/docs/latest/securing_apps/

---

Troubleshooting

Error	Likely Cause
Authentication fails after redirect	The sub_id in the role mapping does not match the value of comparison_field in the user's ID token. Verify the value by decoding the token.
Invalid token signature	The jwks_uri is incorrect or the provider has rotated its keys. Confirm the URI against your provider's documentation.
Redirect URI mismatch	The redirect URI registered with the identity provider does not exactly match the one configured in Devii.
confid not found	Ensure you are using the confid returned by create_oidc_config, not the providerid.