diff --git a/docs/kratos/social-signin/84_uaepass.mdx b/docs/kratos/social-signin/84_uaepass.mdx new file mode 100644 index 000000000..f8968cd7f --- /dev/null +++ b/docs/kratos/social-signin/84_uaepass.mdx @@ -0,0 +1,271 @@ +--- +id: uaepass +title: Add UAE PASS as a social sign-in provider in Ory +sidebar_label: UAE PASS +--- + +# UAE PASS + +[UAE PASS](https://uaepass.ae/) is the UAE's official digital identity platform. It allows UAE nationals, residents, and visitors +to authenticate using their UAE digital identity. Ory supports both web and mobile authentication flows for UAE PASS. + +````mdx-code-block +import JsonnetWarning from "../../_common/jsonnetwarning.mdx" +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +Follow these steps to add UAE PASS as a social sign-in provider for your project, using the Ory Console. + +1. Go to . +1. Enable the **Enable OpenID Connect** toggle, then click **Add new OpenID Connect provider**. +1. Click the UAE PASS logo to open the **Configure UAE PASS** screen. You may need to click **Show more providers** to see the full list of providers. +1. Copy the Redirect URI and save it for later use. +1. Register your application on the [UAE PASS partner portal](https://docs.uaepass.ae/). You will receive a Client ID and Client Secret. +1. Paste the **Client ID** and **Client Secret** into the corresponding fields in the Ory Console's **Configure UAE PASS** screen. +1. Set the **Issuer URL** based on your environment: + - **Production**: `https://id.uaepass.ae` + - **Staging**: `https://stg-id.uaepass.ae` +1. Select the **Authentication Channel**: + - **Web**: For browser-based authentication. + - **Mobile**: For mobile app-to-app integration. +1. In the Ory Console, click **Save Configuration** to enable UAE PASS as a social sign-in provider. +1. In the UAE PASS application configuration, paste the Redirect URI you copied from Ory into the allowed redirect URIs. + +### Data mapping + +In the **Data mapping** field, you can map the data returned by the sign-in provider to traits as defined in the identity +schema. + +To define the mapping, create a Jsonnet code snippet. Read [this document](./data-mapping) to learn more about Jsonnet data +mapping. + +In this sample Jsonnet snippet, the user's `email` and `fullnameEN` are mapped to the identity schema. + +```jsonnet +local claims = std.extVar('claims'); + +{ + identity: { + traits: { + [if 'sub' in claims then 'subject' else null]: claims.sub, + [if 'email' in claims then 'email' else null]: claims.email, + [if 'fullnameEN' in claims then 'name' else null]: claims.fullnameEN, + }, + }, +} +``` + + + +Follow these steps to add UAE PASS as a social sign-in provider to your project using the Ory CLI: + +1. Register your application on the [UAE PASS partner portal](https://docs.uaepass.ae/). You will receive a Client ID + and Client Secret. +1. In the created app, set the redirect URI to: + + ```shell + https://$PROJECT_SLUG.projects.oryapis.com/self-service/methods/oidc/callback/uaepass + ``` + +1. Create a Jsonnet code snippet to map the desired claims to the Ory Identity schema. + + ```jsonnet + local claims = std.extVar('claims'); + + { + identity: { + traits: { + [if 'sub' in claims then 'subject' else null]: claims.sub, + [if 'email' in claims then 'email' else null]: claims.email, + [if 'fullnameEN' in claims then 'name' else null]: claims.fullnameEN, + }, + }, + } + ``` + + :::info + + UAE PASS returns claims through its userinfo endpoint. Available claims include `sub`, `email`, + `fullnameEN`, `firstnameEN`, `lastnameEN`, `fullnameAR`, `firstnameAR`, `lastnameAR`, `gender`, `dob`, `mobile`, + `nationalityEN`, `userType`, `uuid`, `unifiedID`, and `idn`. Ory fetches these claims and makes them available in + `std.extVar('claims')`. + + ::: + +```mdx-code-block + +``` + +1. Encode the Jsonnet snippet with [Base64](https://www.base64encode.org/) or host it under an URL accessible to Ory Network. + + ```shell + cat your-data-mapping.jsonnet | base64 + ``` + +1. Download the Ory Identities config from your project and save it to a file: + + ```shell + ## List all available workspaces + ory list workspaces + + ## List all available projects + ory list projects --workspace + + ## Get config + ory get identity-config --project --workspace --format yaml > identity-config.yaml + ``` + +1. Add the social sign-in provider configuration to the downloaded config. Add the Jsonnet snippet with mappings as a Base64 + string or provide an URL to the file. + + ```yaml + selfservice: + methods: + oidc: + config: + providers: + - id: uaepass # this is `` in the Authorization callback URL. DO NOT CHANGE IT ONCE SET! + provider: uaepass + client_id: .... # Replace this with the Client ID from UAE PASS + client_secret: .... # Replace this with the Client Secret from UAE PASS + issuer_url: https://id.uaepass.ae # Use https://stg-id.uaepass.ae for staging + uaepass_auth_flow: web # Use "mobile" for mobile app-to-app integration + mapper_url: "base64://{YOUR_BASE64_ENCODED_JSONNET_HERE}" + # Alternatively, use an URL: + # mapper_url: https://storage.googleapis.com/abc-cde-prd/9cac9717f007808bf17f22ce7f4295c739604b183f05ac4afb4 + scope: + - urn:uae:digitalid:profile:general + - urn:uae:digitalid:profile:general:unifiedId + enabled: true + ``` + +1. Update the Ory Identities configuration using the file you worked with: + + ```shell + ory update identity-config --project --workspace --file identity-config.yaml + ``` + + + +```` + +## Configuration + +### Environments + +UAE PASS provides two environments. Set the `issuer_url` accordingly: + +| Environment | Issuer URL | +| ----------- | --------------------------- | +| Production | `https://id.uaepass.ae` | +| Staging | `https://stg-id.uaepass.ae` | + +### Authentication flows + +UAE PASS supports two authentication flows configured through the `uaepass_auth_flow` parameter: + +| Flow | Description | Use case | +| -------- | -------------------------------------- | -------------------------- | +| `web` | Browser-based authentication (default) | Web applications | +| `mobile` | Mobile app-to-app integration | Native mobile applications | + +### Scopes + +UAE PASS uses custom scopes to control which user data is returned. The available scopes depend on the user type. + +**For UAE nationals and residents:** + +| Scope | Description | +| ----------------------------------------------- | -------------------- | +| `urn:uae:digitalid:profile:general` | General profile info | +| `urn:uae:digitalid:profile:general:profileType` | Profile type | +| `urn:uae:digitalid:profile:general:unifiedId` | Unified ID | + +**For visitors:** + +| Scope | Description | +| --------------------------- | ------------- | +| `urn:uae:digitalid:profile` | Basic profile | + +For more information on scopes and endpoints, refer to the +[UAE PASS documentation](https://docs.uaepass.ae/feature-guides/authentication/web-application/endpoints). + +### User claims + +UAE PASS returns the following claims. Use these in your Jsonnet data mapping to populate identity traits. + +| Claim | Description | +| --------------- | ------------------------------ | +| `sub` | Subject identifier (unique ID) | +| `email` | Email address | +| `fullnameEN` | Full name (English) | +| `firstnameEN` | First name (English) | +| `lastnameEN` | Last name (English) | +| `fullnameAR` | Full name (Arabic) | +| `firstnameAR` | First name (Arabic) | +| `lastnameAR` | Last name (Arabic) | +| `uuid` | UUID identifier | +| `unifiedID` | UAE unified identifier | +| `idn` | Identity number | +| `userType` | Profile type (SOP1/SOP2/SOP3) | +| `nationalityEN` | Nationality | +| `gender` | Gender | +| `dob` | Date of birth | +| `mobile` | Mobile number | + +**User types:** + +- **SOP1**: UAE National +- **SOP2**: Resident +- **SOP3**: Visitor + +### Advanced data mapping + +To map additional UAE PASS claims to your identity schema, use a more comprehensive Jsonnet snippet: + +```jsonnet +local claims = std.extVar('claims'); + +{ + identity: { + traits: { + [if 'sub' in claims then 'subject' else null]: claims.sub, + [if 'email' in claims then 'email' else null]: claims.email, + [if 'fullnameEN' in claims then 'name' else null]: { + full: claims.fullnameEN, + [if 'firstnameEN' in claims then 'first' else null]: claims.firstnameEN, + [if 'lastnameEN' in claims then 'last' else null]: claims.lastnameEN, + }, + [if 'fullnameAR' in claims then 'name_ar' else null]: { + full: claims.fullnameAR, + [if 'firstnameAR' in claims then 'first' else null]: claims.firstnameAR, + [if 'lastnameAR' in claims then 'last' else null]: claims.lastnameAR, + }, + [if 'unifiedID' in claims then 'unified_id' else null]: claims.unifiedID, + [if 'userType' in claims then 'user_type' else null]: claims.userType, + [if 'nationalityEN' in claims then 'nationality' else null]: claims.nationalityEN, + [if 'gender' in claims then 'gender' else null]: claims.gender, + [if 'dob' in claims then 'date_of_birth' else null]: claims.dob, + [if 'mobile' in claims then 'phone' else null]: claims.mobile, + }, + }, +} +``` + +:::note + +Your Ory Identity schema must include the corresponding fields for any claims you map. Update your identity schema to include the +fields you need before configuring the data mapping. + +::: + +## Troubleshooting + +```mdx-code-block +import SocialSigninTroubleshooting from '../_common/social-sign-in-troubleshooting.mdx' + + +``` diff --git a/src/sidebar.ts b/src/sidebar.ts index d934da661..0497771a5 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -59,6 +59,7 @@ const oidcSSO: SidebarItemConfig = { "kratos/social-signin/x-twitter", "kratos/social-signin/line", "kratos/social-signin/amazon", + "kratos/social-signin/uaepass", ], }, "kratos/social-signin/data-mapping",