Home

Yral Auth V2

Background

Yral Auth V2 follows standard OAuth 2.0 flows with minor extensions. Refer to oauth.com for comprehensive OAuth 2.0 documentation.

Keywords

user_principal

The principal of the user

<Yral Signature>

JSON encoded signature from https://github.com/yral-dapp/yral-identity-ts/pkgs/npm/identity

DelegatedIdentityWire

An ICP compatible DelegatedIdentity, serialized to be transport-friendly

{
  "from_key": [31, 32, 55, 33], // large list of bytes
  "to_secret": {/*Json Web Key, usually secp256k1*/},
  "delegation_chain": [{/*Signed Delegation*/}] // list of signed delegations
}

Typescript example of converting DelegatedIdentityWire to an IC-compatible Delegated Identity:

https://github.com/yral-dapp/download-upload-service/blob/main/src/identity.ts#L51-L76

https://github.com/yral-dapp/download-upload-service/blob/main/src/identity.ts#L18-L29

Endpoints

Base: https://yral-auth-v2.fly.dev/

Token Endpoint: /oauth/token

Authorization Endpoint: /oauth/auth

RFC 8414 (Authorization Server Metadata) is not supported

Supported Flows

Authorization Code Flow with SHA256 PKCE Challenge

Note: PKCE challenge with SHA256 is mandatory

Note: Only response_type=code is supported

Note: Only response_mode=query is supported

Supported Scopes: openid

Token Grant with Authorization Code

Note: Client credentials are passed in request body

Note: Web Clients MUST pass client_secret

Note: Mobile/Native clients needn't pass client_secret

Token Grant with Refresh Token

Note: Client credentials are passed in request body

Note: Web Clients MUST pass client_secret

Note: Mobile/Native clients needn't pass client_secret

Token Grant with Client Credentials

This flow is used for generating anonymous identities. Each call will generate a distinct and separate identity

Note: Web Clients MUST pass client_secret

Note: Mobile/Native clients needn't pass client_secret

Extensions

Login Hint is used for connecting anonymous identities to logged in identities

login_hint parameter must be passed in the authorization code flow, if you want to connect an existing anonymous account(generated with client credentials flow) to a social account(e.g google).

login_hint must be the following JSON object, URL encoded:

{
  "user_principal":  "/*Principal*/",
  "signature": {/* Yral Signature*/}
}

The following message must be signed with @yral-dapp/identity

const msg = new Messsage()
  .withMethodName("yral_auth_v2_login_hint")

Token Verification

A JWK endpoint is not directly exposed, the following EdDSA PEM key can be used to verify JWT tokens returned from Toke Grant Flows:

-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEA04mJta0mU/O+rAVAjNzJxEWp+U8GKksjEI+vbepDfsQ=
-----END PUBLIC KEY----

Token Claims

The following claims are provided in the JWT Token from token grant flow:

{
    "aud": "/*Client ID*/",
    "exp": 11414321413, // Expiry in Epoch seconds, usually 7 days after "iat"
    "iat": 11413332113, // Issued At time in Epoch Seconds
    "iss": "/*Issuer host*/", // usually "yral-auth-v2.fly.dev"
    "sub": "/* Principal Of the Identity*/",
    "nonce": "xyz131231", // Optionally set if client set a nonce during authorization code flow
    "ext_is_anonymous": false, // Whether this identity anonymous or not
    "ext_delegated_identity": {/*DelegatedIdentityWire*/}
}

The returned delegated identity is valid for 7 days. The refresh token is valid for 30 days.