OAuth/SSO initiation endpoints are publicly accessible. Callback endpoints issue JWT tokens.
OAuth & SSO
Integrate OAuth 2.0 and Single Sign-On for seamless authentication.
Overview
Olympus Cloud supports multiple OAuth and SSO providers:
| Provider | Type | Use Case |
|---|---|---|
| OAuth 2.0 | Consumer social login | |
| Microsoft | OAuth 2.0 / Azure AD | Enterprise SSO |
| Apple | OAuth 2.0 | iOS app login |
| Okta | SAML / OIDC | Enterprise identity |
| Auth0 | OIDC | Identity management |
| Custom SAML | SAML 2.0 | Enterprise SSO |
OAuth 2.0 Flow
Authorization Code Flow
┌──────────┐ ┌───────────────┐ ┌──────────────┐
│ Client │────▶│ Olympus Auth │────▶│ Provider │
│ App │ │ Server │ │ (Google, MS) │
└──────────┘ └───────────────┘ └──────────────┘
│ │ │
│ 1. Start OAuth │ │
│─────────────────▶│ │
│ │ 2. Redirect │
│◀─────────────────│────────────────────▶│
│ │ │
│ 3. User authorizes at provider │
│◀───────────────────────────────────────│
│ │ │
│ 4. Callback with code │
│─────────────────▶│ 5. Exchange code │
│ │────────────────────▶│
│ │◀────────────────────│
│ 6. Return tokens │ │
│◀─────────────────│ │
OAuth Callback Endpoints
OAuth providers redirect users back to these callback endpoints after authorization. The Go API Gateway proxies these to the Rust auth service.
Google OAuth Callback
GET /api/v1/auth/google/callback?code={code}&state={tenant_slug}
| Parameter | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Authorization code from Google |
state | string | No | Tenant slug for multi-tenant resolution |
code_verifier | string | No | PKCE code verifier (RFC 7636) for mobile/SPA flows |
Apple OAuth Callback
GET /api/v1/auth/apple/callback?code={code}&state={tenant_slug}
| Parameter | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Authorization code from Apple |
state | string | No | Tenant slug for multi-tenant resolution |
code_verifier | string | No | PKCE code verifier (RFC 7636) |
Generic OAuth Provider Callback
GET /api/v1/auth/oauth/{provider}/callback?code={code}&state={state}
POST /api/v1/auth/oauth/{provider}/callback
Response (all OAuth callbacks)
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g...",
"token_type": "Bearer",
"expires_in": 3600
}
Enterprise SSO
SSO Initiation
Start an SSO login flow by posting to the SSO initiation endpoint.
POST /api/v1/auth/sso/init
Content-Type: application/json
{
"provider_id": "provider-uuid",
"tenant_slug": "demo-restaurant",
"redirect_uri": "https://app.example.com/callback"
}
An alias endpoint POST /api/v1/auth/sso/initiate is also available.
SSO Callback
The IdP redirects users back to the SSO callback endpoint:
GET /api/v1/auth/sso/callback?code={code}&state={state}
POST /api/v1/auth/sso/callback
The Go API Gateway also registers a root-level callback at /auth/sso/callback (without /v1 prefix) for OAuth providers that cannot include custom path prefixes.
SSO Provider Discovery
POST /api/v1/auth/sso/providers
GET /api/v1/auth/sso/providers?tenant_slug={slug}
Returns the list of configured SSO providers for a tenant.
SSO Configuration
GET /api/v1/auth/sso/config?tenant_slug={slug}
Returns the SSO configuration for a tenant.
SAML Assertion Consumer Service (ACS)
POST /api/v1/auth/sso/saml/acs
This is the SAML ACS endpoint where the Identity Provider posts SAML assertions. It accepts application/x-www-form-urlencoded form data containing the SAMLResponse.
SAML SP Metadata
GET /api/v1/auth/saml/metadata
Returns the SAML Service Provider metadata XML document for configuring your IdP.
SAML Configuration (for IdP setup)
| Setting | Value |
|---|---|
| SP Metadata URL | https://api.olympuscloud.ai/v1/auth/saml/metadata |
| ACS URL | https://api.olympuscloud.ai/v1/auth/sso/saml/acs |
There is no SLO (Single Logout) endpoint. SAML logout is not currently implemented.
Required SAML Attributes
| Attribute | Required | Description |
|---|---|---|
email | Yes | User's email address |
firstName | No | First name |
lastName | No | Last name |
groups | No | Group memberships |
Role Mapping
Map external groups to Olympus roles:
{
"role_mappings": [
{
"external_group": "Restaurant Managers",
"olympus_role": "manager"
},
{
"external_group": "Restaurant Staff",
"olympus_role": "staff"
}
],
"default_role": "staff"
}
Admin SSO Provider Management
These endpoints allow platform administrators to manage SSO provider configurations.
List SSO Providers (Admin)
GET /api/v1/auth/admin/sso/providers
Authorization: Bearer {admin_access_token}
Create SSO Provider (Admin)
POST /api/v1/auth/admin/sso/providers
Authorization: Bearer {admin_access_token}
Content-Type: application/json
Get SSO Provider (Admin)
GET /api/v1/auth/admin/sso/providers/{provider_id}
Authorization: Bearer {admin_access_token}
Update SSO Provider (Admin)
PUT /api/v1/auth/admin/sso/providers/{provider_id}
Authorization: Bearer {admin_access_token}
Content-Type: application/json
Delete SSO Provider (Admin)
DELETE /api/v1/auth/admin/sso/providers/{provider_id}
Authorization: Bearer {admin_access_token}
Test SSO Provider (Admin)
POST /api/v1/auth/admin/sso/providers/{provider_id}/test
Authorization: Bearer {admin_access_token}
Firebase Token Exchange
Exchange a Firebase ID token for Olympus JWT tokens:
POST /api/v1/auth/firebase/exchange
Content-Type: application/json
{
"firebase_token": "firebase_id_token_here"
}
Error Responses
| Error | Code | Description |
|---|---|---|
| Invalid State | 400 | State parameter mismatch |
| Provider Error | 401 | Authentication failed at provider |
| Domain Not Allowed | 403 | Email domain not authorized |