Advanced OAuth 2.0 API

Auris supports several advanced OAuth 2.0 and OpenID Connect extensions beyond the standard Authorization Code + PKCE flow. These capabilities are designed for enterprise and specialized authentication scenarios:

• Device Authorization (RFC 8628) — for input-constrained devices like CLIs, smart TVs, and IoT
• Token Exchange (RFC 8693) — for impersonation and delegation between services
• DPoP (RFC 9449) — for sender-constrained tokens that are resistant to token theft
• CIBA (Client-Initiated Backchannel Authentication) — for authentication initiated by a backend service without browser interaction
• Adaptive MFA / Risk Assessment — for dynamic step-up authentication based on risk scoring

All advanced OAuth features must be enabled per-application in the Auris Console under Applications > [App] > Advanced OAuth.

Device Authorization (RFC 8628)

The Device Authorization Grant allows devices that cannot display a browser (CLIs, smart TVs, IoT devices, kiosks) to authenticate users. The device displays a short user code and a verification URL; the user visits the URL on a separate device (phone, laptop) and enters the code to approve.

Request body

{
  "client_id": "cli-app-client-id",
  "scope": "openid profile email"
}

Success response

{
  "ok": true,
  "data": {
    "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
    "user_code": "WDJB-MJHT",
    "verification_uri": "https://api.altovar.net/hosted/device",
    "verification_uri_complete": "https://api.altovar.net/hosted/device?user_code=WDJB-MJHT",
    "expires_in": 1800,
    "interval": 5
  }
}

Error codes

Polling for Tokens

After displaying the user code, the device polls the token endpoint at the specified interval:

Request body

{
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "client_id": "cli-app-client-id"
}

Pending response (user has not yet approved)

{
  "ok": false,
  "error": {
    "code": "AUTHORIZATION_PENDING",
    "message": "The user has not yet approved the request. Continue polling."
  }
}

Slow down response (polling too frequently)

{
  "ok": false,
  "error": {
    "code": "SLOW_DOWN",
    "message": "Polling too frequently. Increase interval by 5 seconds."
  }
}

Success response (user approved)

{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Error codes during polling

User Verification Page

Auris provides a hosted verification page at /hosted/device where the user:

1. Enters the 8-character user code (or arrives via verification_uri_complete with the code pre-filled)
2. Authenticates using any configured method (password, SSO, magic link, 2FA)
3. Approves the device authorization request
4. Sees a confirmation screen and can close the tab

Token Exchange (RFC 8693)

Token Exchange allows a service to exchange one token for another — either to impersonate a user (act as them) or to delegate access (act on behalf of them while retaining the original subject). This is essential for microservice architectures where an API gateway needs to call downstream services with different token scopes.

Request body — Impersonation

Impersonation replaces the subject entirely. The resulting token has the target user as the sub claim. Use this when an admin needs to act as a user for debugging.

{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiJ9...",
  "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "exchange_type": "impersonation",
  "target_user_id": "usr_target123"
}

Request body — Delegation

Delegation preserves the original subject and adds an act (actor) claim to the resulting token. The downstream service can see both who the token is for and who is acting on their behalf.

{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiJ9...",
  "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "exchange_type": "delegation"
}

Success response — Impersonation

{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "issuedTokenType": "urn:ietf:params:oauth:token-type:access_token",
    "tokenType": "Bearer",
    "expiresIn": 900
  }
}

The impersonated token’s JWT payload will have "sub": "usr_target123" with the impersonating user’s original identity recorded in audit logs.

Success response — Delegation

{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "issuedTokenType": "urn:ietf:params:oauth:token-type:access_token",
    "tokenType": "Bearer",
    "expiresIn": 900
  }
}

The delegated token’s JWT payload includes an act claim:

{
  "sub": "usr_original_user",
  "act": {
    "sub": "usr_acting_service"
  },
  "scope": "read:users"
}

Error codes

DPoP — Sender-Constrained Tokens (RFC 9449)

Demonstration of Proof-of-Possession (DPoP) binds tokens to a specific client by requiring a cryptographic proof with each request. Even if a DPoP-bound token is stolen, it cannot be used without the corresponding private key.

How DPoP Works

1. The client generates a key pair (typically EC P-256 or RSA) and keeps the private key secure.
2. On each request, the client creates a signed DPoP proof JWT containing the HTTP method, URL, and a unique jti.
3. The server validates the proof, extracts the JWK thumbprint, and binds the issued token to that key.
4. Subsequent API calls must include both the DPoP token and a fresh DPoP proof signed with the same key.

Requesting DPoP-Bound Tokens

Include a DPoP header with any token request (login, refresh, authorization code exchange):

POST /api/auth/token HTTP/1.1
Content-Type: application/json
DPoP: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiLi4uIiwieSI6Ii4uLiJ9fQ.eyJodG0iOiJQT1NUIiwiaHR1IjoiaHR0cHM6Ly95b3VyLWF1cmlzLWRvbWFpbi5jb20vYXBpL2F1dGgvdG9rZW4iLCJpYXQiOjE3MDg1MjEyMDAsImp0aSI6InVuaXF1ZS1pZC0xMjMifQ.signature

DPoP proof JWT structure

Header:

{
  "alg": "ES256",
  "typ": "dpop+jwt",
  "jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "...",
    "y": "..."
  }
}

Payload:

{
  "htm": "POST",
  "htu": "https://api.altovar.net/api/auth/token",
  "iat": 1708521200,
  "jti": "unique-id-123",
  "nonce": "server-provided-nonce"
}

Token response with DPoP

When a DPoP proof is included, the response token is DPoP-bound:

{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "tokenType": "DPoP",
    "expiresIn": 900
  }
}

Note that tokenType is "DPoP" instead of "Bearer". The access token’s JWT contains a cnf (confirmation) claim with the JWK thumbprint:

{
  "sub": "usr_abc123",
  "cnf": {
    "jkt": "JWK_THUMBPRINT_BASE64URL"
  }
}

Nonce Management

The server may require a nonce for replay protection. When it does, the response includes:

DPoP-Nonce: eyJhbGciOiJIUzI1NiJ9...

Include this nonce in subsequent DPoP proofs. If a request arrives without a required nonce, the server returns 400 with a use_dpop_nonce error and a fresh nonce in the header.

Error codes

CIBA — Client-Initiated Backchannel Authentication

CIBA allows a backend service to initiate authentication for a user without requiring the user to interact with a browser redirect. Instead, the user receives a notification (push, SMS, or email) and approves the request on their device.

This is useful for scenarios like call center authentication (“I’m calling from your bank, please approve the login on your phone”) or point-of-sale transactions.

Request body

{
  "client_id": "backend-service-id",
  "client_secret": "backend-service-secret",
  "scope": "openid profile",
  "login_hint": "[email protected]",
  "binding_message": "Approve login for Order #12345",
  "requested_expiry": 300
}

Success response

{
  "ok": true,
  "data": {
    "auth_req_id": "ciba_req_abc123def456",
    "expires_in": 300,
    "interval": 5
  }
}

Notification Modes

CIBA supports three notification delivery modes, configured per-application:

Polling for CIBA Tokens

For poll mode, the service polls the token endpoint:

{
  "grant_type": "urn:openid:params:grant-type:ciba",
  "auth_req_id": "ciba_req_abc123def456",
  "client_id": "backend-service-id",
  "client_secret": "backend-service-secret"
}

The polling responses follow the same pattern as Device Authorization:

• AUTHORIZATION_PENDING while waiting for user approval
• SLOW_DOWN if polling too frequently
• EXPIRED_TOKEN if the request timed out
• ACCESS_DENIED if the user rejected the request
• Full token response on approval

Error codes

Risk Assessment and Adaptive MFA

Auris performs automatic risk assessment on every authentication attempt. The risk score is computed from five weighted factors and determines whether additional authentication steps (step-up MFA) are required.

Risk Scoring Factors

Risk levels: LOW (0-30), MEDIUM (31-60), HIGH (61-80), CRITICAL (81-100).

When the risk score exceeds configured thresholds, Auris automatically challenges the user with step-up MFA before issuing tokens. The acr (Authentication Context Class Reference) and amr (Authentication Methods References) claims in the JWT reflect the actual authentication level achieved.

Query parameters

Success response

{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "risk_abc123",
        "userId": "usr_def456",
        "score": 72,
        "level": "HIGH",
        "factors": {
          "ipReputation": { "score": 85, "isVpn": true, "isProxy": false },
          "deviceTrust": { "score": 50, "isNewDevice": true },
          "geoAnomaly": { "score": 90, "distance": 5200, "timeSinceLastLogin": 1800 },
          "behavior": { "score": 60, "unusualTime": true },
          "actionSensitivity": { "score": 75 }
        },
        "actionTaken": "step_up_mfa",
        "ipAddress": "203.0.113.42",
        "country": "CN",
        "city": "Beijing",
        "createdAt": "2025-02-18T03:45:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 156, "totalPages": 8 }
  }
}

Success response

{
  "ok": true,
  "data": [
    {
      "id": "rule_abc123",
      "name": "Block known VPN ranges",
      "condition": {
        "field": "ipReputation.isVpn",
        "operator": "equals",
        "value": true
      },
      "action": "block",
      "scoreModifier": 40,
      "isActive": true,
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ]
}

Request body

{
  "name": "Require MFA for new countries",
  "condition": {
    "field": "geoAnomaly.isNewCountry",
    "operator": "equals",
    "value": true
  },
  "action": "step_up_mfa",
  "scoreModifier": 30,
  "isActive": true
}

Available condition fields: ipReputation.isVpn, ipReputation.isProxy, ipReputation.isDatacenter, deviceTrust.isNewDevice, geoAnomaly.isNewCountry, geoAnomaly.distance, behavior.unusualTime, behavior.failedAttempts.

Available operators: equals, not_equals, greater_than, less_than, contains, in.

Success response

{
  "ok": true,
  "data": {
    "id": "rule_def456",
    "name": "Require MFA for new countries",
    "condition": {
      "field": "geoAnomaly.isNewCountry",
      "operator": "equals",
      "value": true
    },
    "action": "step_up_mfa",
    "scoreModifier": 30,
    "isActive": true,
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Request body

{
  "name": "Require MFA for new countries (updated)",
  "scoreModifier": 50,
  "isActive": true
}

Success response

{
  "ok": true,
  "data": { "deleted": true }
}

ACR and AMR in Tokens

When adaptive MFA triggers step-up authentication, the issued JWT includes acr and amr claims that downstream services can use to verify the authentication strength:

{
  "sub": "usr_abc123",
  "acr": "urn:auris:acr:mfa",
  "amr": ["pwd", "otp"],
  "iat": 1708521200,
  "exp": 1708522100
}

Resource servers can require a minimum acr level for sensitive operations by checking the JWT claims before processing the request.

Permissions Reference

Related

• DPoP (Proof of Possession) — How DPoP proof validation works
• Device Authorization Flow — Device flow protocol details
• CIBA (Backchannel Auth) — CIBA protocol architecture
• Token Exchange (RFC 8693) — Token exchange protocol details
• Implementing DPoP — Step-by-step DPoP integration
• Device Authorization Flow — Device flow integration guide
• CIBA Guide — CIBA integration walkthrough
• Token Exchange — Impersonation and delegation guide
• Advanced OAuth2 — Configure advanced OAuth2 features from the Console