OIDC Provider Setup¶

Step-by-step instructions for configuring common identity providers with ShoreGuard. For general OIDC configuration, see the OIDC / SSO guide.

The callback URL for all providers is:

https://<your-shoreguard-domain>/api/auth/oidc/callback

Google Workspace¶

Go to the Google Cloud Console
Create a new project (or select an existing one)
Navigate to APIs & Services > Credentials
Click Create Credentials > OAuth client ID
Application type: Web application
Add the ShoreGuard callback URL to Authorized redirect URIs
Copy the Client ID and Client secret

{
  "name": "google",
  "display_name": "Google",
  "issuer": "https://accounts.google.com",
  "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
  "client_secret": "GOCSPX-YOUR_SECRET"
}

Microsoft Entra ID (Azure AD)¶

Go to the Azure Portal
Navigate to Microsoft Entra ID > App registrations > New registration
Name: ShoreGuard
Supported account types: choose based on your needs (single tenant or multi-tenant)
Redirect URI: Web → your ShoreGuard callback URL
Under Certificates & secrets, create a new client secret
Copy the Application (client) ID and Client secret value
Note your Directory (tenant) ID

{
  "name": "entra",
  "display_name": "Microsoft Entra",
  "issuer": "https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0",
  "client_id": "YOUR_APPLICATION_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Role mapping via groups¶

To map Entra group membership to ShoreGuard roles:

In the app registration, go to Token configuration > Add groups claim
Select Security groups and choose Group ID as the claim format
Add the group object IDs to the role mapping:

{
  "name": "entra",
  "display_name": "Microsoft Entra",
  "issuer": "https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0",
  "client_id": "YOUR_APPLICATION_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "role_mapping": {
    "claim": "groups",
    "values": {
      "ADMIN_GROUP_OBJECT_ID": "admin",
      "OPS_GROUP_OBJECT_ID": "operator"
    }
  }
}

Okta¶

Go to your Okta admin console
Navigate to Applications > Create App Integration
Sign-in method: OIDC — OpenID Connect
Application type: Web Application
Add the ShoreGuard callback URL to Sign-in redirect URIs
Copy the Client ID and Client secret
Note your Okta domain (e.g. dev-12345.okta.com)

{
  "name": "okta",
  "display_name": "Okta",
  "issuer": "https://YOUR_DOMAIN.okta.com",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Keycloak¶

Open the Keycloak admin console
Select your realm (or create a new one)
Navigate to Clients > Create client
Client type: OpenID Connect
Client ID: shoreguard
Enable Client authentication (confidential client)
Add the ShoreGuard callback URL to Valid redirect URIs
Copy the Client secret from the Credentials tab
Note your realm URL

{
  "name": "keycloak",
  "display_name": "Keycloak",
  "issuer": "https://YOUR_KEYCLOAK_HOST/realms/YOUR_REALM",
  "client_id": "shoreguard",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Role mapping via realm roles¶

Keycloak includes roles in the realm_access.roles claim by default. To map these to ShoreGuard roles, use a custom claim or configure Keycloak to include roles in a top-level claim:

{
  "role_mapping": {
    "claim": "roles",
    "values": {
      "shoreguard-admin": "admin",
      "shoreguard-operator": "operator"
    }
  }
}

Multiple providers¶

Configure multiple providers as an array in SHOREGUARD_OIDC_PROVIDERS_JSON. Each provider gets its own login button on the login page.

export SHOREGUARD_OIDC_PROVIDERS_JSON='[
  {"name": "google", "display_name": "Google", "issuer": "https://accounts.google.com", "client_id": "...", "client_secret": "..."},
  {"name": "entra", "display_name": "Microsoft", "issuer": "https://login.microsoftonline.com/TENANT/v2.0", "client_id": "...", "client_secret": "..."}
]'