From 67a0dbc3cbd879777e2762a08d829a7907e2313f Mon Sep 17 00:00:00 2001 From: Carmen Date: Thu, 4 Jun 2026 11:20:05 +0100 Subject: [PATCH 1/2] doc: Update Auth Flow API and UserInfo docs for canonical OAuth field names Rename provider_type/alias to oauth_provider_type/oauth_provider_alias in all Auth Flow API response examples. Add https://authgear.com/claims/user/identities claim to UserInfo endpoint documentation with login_id and oauth identity types. Co-Authored-By: Claude Sonnet 4.6 --- .../custom-ui/authentication-flow-api.md | 4 ++-- reference/apis/authentication-flow-api.md | 22 ++++++++--------- .../userinfo.md | 24 +++++++++++++++++++ 3 files changed, 37 insertions(+), 13 deletions(-) diff --git a/customization/ui-customization/custom-ui/authentication-flow-api.md b/customization/ui-customization/custom-ui/authentication-flow-api.md index 64ee577..3624874 100644 --- a/customization/ui-customization/custom-ui/authentication-flow-api.md +++ b/customization/ui-customization/custom-ui/authentication-flow-api.md @@ -60,8 +60,8 @@ The following is a sample of the response you would get from the Authentication }, { "identification": "oauth", - "provider_type": "google", - "alias": "google" + "oauth_provider_type": "google", + "oauth_provider_alias": "google" } ] } diff --git a/reference/apis/authentication-flow-api.md b/reference/apis/authentication-flow-api.md index 71bdcb7..fd787d1 100644 --- a/reference/apis/authentication-flow-api.md +++ b/reference/apis/authentication-flow-api.md @@ -438,13 +438,13 @@ When you make the above HTTP request to create a signup flow, you get a response }, { "identification": "oauth", - "provider_type": "google", - "alias": "google" + "oauth_provider_type": "google", + "oauth_provider_alias": "google" }, { "identification": "oauth", - "provider_type": "wechat", - "alias": "wechat_mobile", + "oauth_provider_type": "wechat", + "oauth_provider_alias": "wechat_mobile", "wechat_app_type": "mobile" } ] @@ -545,8 +545,8 @@ The response for the above HTTP request will look like this: }, { "identification": "oauth", - "provider_type": "wechat", - "alias": "wechat_mobile", + "oauth_provider_type": "wechat", + "oauth_provider_alias": "wechat_mobile", "wechat_app_type": "mobile" } ] @@ -884,12 +884,12 @@ Presence in response: ``` { "identification": "oauth", - "provider_type": "google", - "alias": "google" + "oauth_provider_type": "google", + "oauth_provider_alias": "google" } ``` -* `provider_type`: The expected value here is a keyword for a specific OAuth provider. Possible values are: +* `oauth_provider_type`: The type of OAuth provider. Possible values are: * `google` * `facebook` * `github` @@ -899,7 +899,7 @@ Presence in response: * `adfs` * `apple` * `wechat` -* `alias`: The identifier of the OAuth provider. You pass this in the input. +* `oauth_provider_alias`: The configured alias of the OAuth provider. Pass this value as `alias` in the input. Usage in input: @@ -923,8 +923,8 @@ The response to an Authentication Flow API request with the above input should l "type": "identify", "identification": "oauth", "data": { - "alias": "google", "oauth_provider_type": "google", + "oauth_provider_alias": "google", "oauth_authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=850158775140-cuov06p5ru3kq27n4bfvrlp3fb7vrpgd.apps.googleusercontent.com&prompt=select_account&redirect_uri=http%3A%2F%2Flocalhost%3A3000&response_type=code&scope=openid+profile+email" } } diff --git a/reference/apis/oauth-2.0-and-openid-connect-oidc/userinfo.md b/reference/apis/oauth-2.0-and-openid-connect-oidc/userinfo.md index 11f37be..91e076e 100644 --- a/reference/apis/oauth-2.0-and-openid-connect-oidc/userinfo.md +++ b/reference/apis/oauth-2.0-and-openid-connect-oidc/userinfo.md @@ -32,6 +32,22 @@ The following code shows an example of the structure and some information that's "given_name": "Doe", "phone_number": "0805551112", "phone_number_verified": true, + "https://authgear.com/claims/user/identities": [ + { + "type": "login_id", + "created_at": "2025-06-04T10:50:00.000000Z", + "updated_at": "2025-06-04T10:50:00.000000Z", + "login_id_key": "email", + "login_id_type": "email" + }, + { + "type": "oauth", + "created_at": "2025-06-04T10:52:00.000000Z", + "updated_at": "2025-06-04T10:52:00.000000Z", + "oauth_provider_type": "google", + "oauth_provider_alias": "google" + } + ], "https://authgear.com/claims/user/authenticators": [ { "created_at": "2025-06-04T10:50:00.00000Z", @@ -69,6 +85,14 @@ The following section explains each standard attribute and examples of some cust * `given_name`: givenname of the current user. * `gender`: holds the value set for the current users' gender (male, female, or some other string). * `sub`: sub is short for "subject" and it is a standard field in O. The value is the user's unique ID generated by Authgear. You can use this user ID to generate a [user node ID](../../../reference/apis/admin-api/using-global-node-ids.md#id-1.-generate-id-for-user-node-type) which you can then use in **Admin API** to query a user or perform mutations. +* `https://authgear.com/claims/user/identities`: this field contains an array of [identities](../../../concepts/user-identity-and-authenticator.md#identity) linked to the user. Each element always includes: + * `type`: identity type — `login_id`, `oauth`, `passkey`, `biometric`, `anonymous`, `siwe`, or `ldap` + * `created_at`: the timestamp of when the identity was created + * `updated_at`: the timestamp of when the identity was last updated + + Additional fields are present depending on `type`: + * For `login_id`: `login_id_key` (configured key name, e.g. `"email"`) and `login_id_type` (resolved type: `"email"`, `"phone"`, or `"username"`) + * For `oauth`: `oauth_provider_type` (e.g. `"google"`) and `oauth_provider_alias` (the configured alias) * `https://authgear.com/claims/user/authenticators` : this field contains an array of information of [authenticators](../../../concepts/user-identity-and-authenticator.md#authenticator) owned by the user. * `created_at`: the timestamp of when the authenticator was created * `updated_at`: the timestamp of when the authenticator was last updated From e35d0973f60d0806880a3b480d8c9afe8033f937 Mon Sep 17 00:00:00 2001 From: Carmen Date: Thu, 4 Jun 2026 11:23:03 +0100 Subject: [PATCH 2/2] doc: Rename :alias to :oauth_provider_alias in provider redirect URI docs Co-Authored-By: Claude Sonnet 4.6 --- .../enterprise-login-providers/adfs.md | 2 +- .../enterprise-login-providers/azureadv2.md | 2 +- .../social-login-providers/apple.md | 2 +- .../social-login-providers/facebook.md | 2 +- .../social-login-providers/google.md | 2 +- .../social-login-providers/linkedin.md | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/authentication-and-access/social-enterprise-login-providers/enterprise-login-providers/adfs.md b/authentication-and-access/social-enterprise-login-providers/enterprise-login-providers/adfs.md index e49e4d2..1ddc5ff 100644 --- a/authentication-and-access/social-enterprise-login-providers/enterprise-login-providers/adfs.md +++ b/authentication-and-access/social-enterprise-login-providers/enterprise-login-providers/adfs.md @@ -6,7 +6,7 @@ 2. Create an application in your AD FS Server, obtain "Client ID", "Client Secret" and "Discovery Document Endpoint". Discovery Document Endpoint typically ends with `/.well-known/openid-configuration`. Configure your application with redirect uri `https:///sso/oauth2/callback/adfs`. {% hint style="info" %} -Redirect URI has the form of `/sso/oauth2/callback/:alias`. The `alias` is used as the identifier of OAuth provider. You can configure the `alias` in Authgear Portal. +Redirect URI has the form of `/sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal. {% endhint %} ## Configure Sign in with Microsoft AD FS through the portal diff --git a/authentication-and-access/social-enterprise-login-providers/enterprise-login-providers/azureadv2.md b/authentication-and-access/social-enterprise-login-providers/enterprise-login-providers/azureadv2.md index b4d71b0..32e24a3 100644 --- a/authentication-and-access/social-enterprise-login-providers/enterprise-login-providers/azureadv2.md +++ b/authentication-and-access/social-enterprise-login-providers/enterprise-login-providers/azureadv2.md @@ -16,7 +16,7 @@ 6. Follow [this](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#add-a-client-secret) section to add a client secret. Remember to record the secret value when you add the client secret, as it will not be displayed again. This will be needed for configure OAuth client in Authgear. {% hint style="info" %} -Redirect URI has the form of `/sso/oauth2/callback/:alias`. The `alias` is used as the identifier of OAuth provider. You can configure the `alias` in Authgear Portal. +Redirect URI has the form of `/sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal. {% endhint %} ## Configure Sign in with Microsoft through the portal diff --git a/authentication-and-access/social-enterprise-login-providers/social-login-providers/apple.md b/authentication-and-access/social-enterprise-login-providers/social-login-providers/apple.md index eebb732..1639737 100644 --- a/authentication-and-access/social-enterprise-login-providers/social-login-providers/apple.md +++ b/authentication-and-access/social-enterprise-login-providers/social-login-providers/apple.md @@ -18,7 +18,7 @@ To configure "Sign in with Apple" for Authgear, you will need to fulfil the foll 10. Create a "Key" following [this guide](https://developer.apple.com/help/account/manage-keys/create-a-private-key) with "Sign in with Apple" enabled. Click "Configure" next to "Sign in with Apple" and select "Primary App ID" with app ID created above. Keep the private key safe, you need to provide this later. {% hint style="info" %} -Redirect URI has the form of `/sso/oauth2/callback/:alias`. The `alias` is used as the identifier of OAuth provider. You can configure the `alias` in Authgear Portal. +Redirect URI has the form of `/sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal. {% endhint %} ## Configure Sign in with Apple in Authgear Portal diff --git a/authentication-and-access/social-enterprise-login-providers/social-login-providers/facebook.md b/authentication-and-access/social-enterprise-login-providers/social-login-providers/facebook.md index b7f5efb..c9ec3a7 100644 --- a/authentication-and-access/social-enterprise-login-providers/social-login-providers/facebook.md +++ b/authentication-and-access/social-enterprise-login-providers/social-login-providers/facebook.md @@ -44,7 +44,7 @@ Follow the on-screen instructions to finish the app creation process.
{% hint style="info" %} -Redirect URI has the form of `https:///sso/oauth2/callback/:alias`. The `alias` is used as the identifier of OAuth provider. You can configure the `alias` in Authgear Portal. +Redirect URI has the form of `https:///sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal. See [Your Authgear Endpoint](../../../reference/glossary.md#your-authgear-endpoint) for instructions on how to get the value for `YOUR_AUTHGEAR_ENDPOINT`. {% endhint %} diff --git a/authentication-and-access/social-enterprise-login-providers/social-login-providers/google.md b/authentication-and-access/social-enterprise-login-providers/social-login-providers/google.md index 4430329..42629b0 100644 --- a/authentication-and-access/social-enterprise-login-providers/social-login-providers/google.md +++ b/authentication-and-access/social-enterprise-login-providers/social-login-providers/google.md @@ -28,7 +28,7 @@ After creating a new project, you will need to configure the OAuth consent scree ![OAuth Client ID in the Credentials page](../../../.gitbook/assets/GCP_create_client_id.png) {% hint style="info" %} -Redirect URI has the form of `/sso/oauth2/callback/:alias`. The `alias` is used as the identifier of OAuth provider. You can configure the `alias` in Authgear Portal. +Redirect URI has the form of `/sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal. {% endhint %} You can find more details in [official Google Cloud Platform doc](https://support.google.com/cloud/answer/6158849) diff --git a/authentication-and-access/social-enterprise-login-providers/social-login-providers/linkedin.md b/authentication-and-access/social-enterprise-login-providers/social-login-providers/linkedin.md index 8fab963..e110dec 100644 --- a/authentication-and-access/social-enterprise-login-providers/social-login-providers/linkedin.md +++ b/authentication-and-access/social-enterprise-login-providers/social-login-providers/linkedin.md @@ -20,7 +20,7 @@ Also, add `https:///sso/oauth2/callback/linkedin` to "Au

LinkedIn app, "Auth" tab

{% hint style="info" %} -The redirect URI has the form of `/sso/oauth2/callback/:alias`. The `alias` is used as the identifier of OAuth provider. You can configure the `alias` in Authgear Portal +The redirect URI has the form of `/sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal {% endhint %} Next, open the **Products** tab of your LinkedIn app, and request access to "Sign In with LinkedIn using OpenID Connect."