diff --git a/.github/workflows/release-docs.yml b/.github/workflows/release-docs.yml index 5256a0e8b3..eb52fe581e 100644 --- a/.github/workflows/release-docs.yml +++ b/.github/workflows/release-docs.yml @@ -90,22 +90,35 @@ jobs: - name: Build MkDocs Documentation run: | + unset ENABLE_HOOKS cd en/asgardeo mkdocs build cd ../../ + - name: Conditionally build MkDocs Documentation + run: | + export ENABLE_HOOKS=true + cd en/asgardeo + mkdocs build --site-dir prod-build + cd ../../ + - name: Zip the Documentation run: | mkdir -p out/asgardeo/docs + mkdir -p out-prod/asgardeo/docs cp -r ./en/asgardeo/site/* out/asgardeo/docs/ + cp -r ./en/asgardeo/prod-build/* out-prod/asgardeo/docs/ zip -r asgardeo-docs-${{ env.NEW_VERSION }}.zip ./out + zip -r asgardeo-docs-${{ env.NEW_VERSION }}-prod.zip ./out-prod - name: Create git tag run: | git config user.name $GIT_USERNAME git config user.email $GIT_USER_EMAIL git tag "v${{ env.NEW_VERSION }}" + git tag "v${{ env.NEW_VERSION }}-prod" git push "https://$GIT_USERNAME:$GITHUB_TOKEN@github.com/${{ github.repository }}" "v${{ env.NEW_VERSION }}" + git push "https://$GIT_USERNAME:$GITHUB_TOKEN@github.com/${{ github.repository }}" "v${{ env.NEW_VERSION }}-prod" - name: Create Release id: create_release @@ -115,6 +128,15 @@ jobs: release_name: Asgardeo Docs - v${{ env.NEW_VERSION }} draft: false prerelease: ${{ env.IS_HOTFIX == 'true' }} + + - name: Create prod release + id: create_prod_release + uses: actions/create-release@v1 + with: + tag_name: v${{ env.NEW_VERSION }}-prod + release_name: Asgardeo Docs - v${{ env.NEW_VERSION }}-prod + draft: false + prerelease: ${{ env.IS_HOTFIX == 'true' }} - name: Upload Release Asset uses: actions/upload-release-asset@v1 @@ -123,6 +145,14 @@ jobs: asset_path: ./asgardeo-docs-${{ env.NEW_VERSION }}.zip asset_name: asgardeo-docs-${{ env.NEW_VERSION }}.zip asset_content_type: application/zip + + - name: Upload Prod Release Asset + uses: actions/upload-release-asset@v1 + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: ./asgardeo-docs-${{ env.NEW_VERSION }}-prod.zip + asset_name: asgardeo-docs-${{ env.NEW_VERSION }}-prod.zip + asset_content_type: application/zip - name: Commit and push new version if: ${{ env.IS_HOTFIX == 'false' }} diff --git a/VERSION b/VERSION index 87df0737be..1887e7e668 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.0.270 +0.0.275 diff --git a/en/asgardeo/docs/apis/restapis/rule-metadata.yaml b/en/asgardeo/docs/apis/restapis/rule-metadata.yaml new file mode 100644 index 0000000000..665cad186b --- /dev/null +++ b/en/asgardeo/docs/apis/restapis/rule-metadata.yaml @@ -0,0 +1,369 @@ +openapi: 3.0.1 +info: + title: Asgardeo Rule Metadata REST API + description: "The Rule Metadata API provides the essential metadata required to configure rules dynamically based on the flow context. \nThe metadata retrieved by this API is designed to support rule configuration in the user interface (UI) by delivering information about each configurable field, the set of applicable comparison operators (e.g., equals, contains) for each field, and lists of possible values or options for fields.\n" + contact: + name: WSO2 + url: https://wso2.com/identity-and-access-management/ + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: v1 +servers: + - url: 'https://api.asgardeo.io/t/{organization-name}/api/server/v1' +security: +- OAuth2: [] +paths: + /rules/metadata: + get: + tags: + - Metadata + summary: Get metadata for rule configuration. + description: |+ + This API provides a list of fields, associated metadata, and applicable operators for each field based on the specified flow type. This information is used to populate the UI for rule configuration. + + Scope (Permission) required: ``internal_rule_metadata_view`` + + operationId: getExpressionMeta + parameters: + - name: flow + in: query + description: | + Specifies the flow to retrieve rule metadata. This ensures that the metadata returned is relevant to the given flow. + + Note: At present, only the 'preIssueAccessToken' flow is supported. + required: true + style: form + explode: true + schema: + type: string + enum: + - preIssueAccessToken + - prePasswordUpdate + - preProfileUpdate + - preLogin + - postLogin + - inLogin + - preRegistration + - inRegistration + - inPasswordExpiry + responses: + "200": + description: Applicable fields and operators + content: + application/json: + schema: + $ref: '#/components/schemas/ExpressionMeta' + examples: + preIssueAccessToken: + summary: Sample response for pre-issue access token flow + value: + - field: + name: application + displayName: application + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: reference + valueReferenceAttribute: id + valueDisplayAttribute: name + links: + - href: /applications?offset=0&limit=10 + method: GET + rel: values + - href: /applications?filter=name+eq+*&limit=10 + method: GET + rel: filter + - field: + name: grantType + displayName: grant type + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: string + values: + - name: authorization_code + displayName: authorization code + - name: password + displayName: password + - name: refresh_token + displayName: refresh token + - name: client_credentials + displayName: client credentials + - name: urn:ietf:params:oauth:grant-type:token-exchange + displayName: token exchange + prePasswordUpdate: + summary: Sample response for pre-password update flow + value: + - field: + name: initiator + displayName: initiator + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: string + values: + - name: user + displayName: user + - name: admin + displayName: admin + - name: application + displayName: application + - field: + name: flow + displayName: flow + dependentFileds: + - initiator + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: string + values: + - name: reset + displayName: reset + - name: update + displayName: update + inLogin: + summary: Sample response for login flow + value: + - field: + name: role + displayName: user.role + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: reference + valueReferenceAttribute: id + valueDisplayAttribute: name + links: + - href: /scim2/Roles?offset=0&limit=10 + method: GET + rel: values + - href: /scim2/Roles?filter=name+eq+*&limit=10 + method: GET + rel: filter + - field: + name: group + displayName: user.group + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: reference + valueReferenceAttribute: id + valueDisplayAttribute: name + links: + - href: /scim2/Groups?offset=0&limit=10 + method: GET + rel: values + - href: /scim2/Groups?filter=name+eq+*&limit=10 + method: GET + rel: filter + - field: + name: email + displayName: user.email + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + - name: startsWith + displayName: starts with + - name: endsWith + displayName: ends with + - name: contains + displayName: contains + value: + inputType: input + valueType: string + "400": + description: Bad Request + "401": + description: Unauthorized + "500": + description: Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codeSamples: + - lang: Curl + source: | + curl --location 'https://api.asgardeo.io/t/{organization-name}/api/server/v1/rules/metadata?flow=preIssueAccessToken' \ + --header 'Authorization: Bearer {bearer_token}' +components: + schemas: + ExpressionMeta: + type: array + description: Represents the metadata for rule expressions. It includes field definitions and associated operators. + items: + $ref: '#/components/schemas/FieldDefinition' + FieldDefinition: + type: object + properties: + field: + $ref: '#/components/schemas/Field' + operators: + type: array + description: | + Specifies the list of valid operators that can be applied to this field in rule expressions. Each operator defines a comparison or matching condition (e.g., \"equals\", \"contains\", \"greaterThan\") that determines how the field's value will be evaluated within a rule. + items: + $ref: '#/components/schemas/Operator' + value: + $ref: '#/components/schemas/Value' + Field: + type: object + properties: + name: + type: string + description: Name of the field. This is an immutable attribute and uniquely identifies the field allowed in the rule. + example: role + displayName: + type: string + description: Display name of the field. Use as a user friendly label of the field to show in UI. + example: user.role + dependantFields: + type: array + description: Lists the names of fields on which this field depends for its display or selection in the next expression. + example: [] + items: + type: string + Value: + type: object + properties: + inputType: + type: string + description: | + Defines how the field should be presented and populated in the rule configuration UI. This property indicates whether the field allows direct user input or if the values are selected from predefined options. Possible types include: + + - "input": Allows for direct user entry, such as text or numeric input. + - "options": Provides a list of selectable values, often fetched from an external data source, enabling users to pick from predefined choices. + enum: + - input + - options + valueType: + type: string + description: | + Specifies the expected data type for the field’s value within a rule expression. This property defines how the field's value should be interpreted when used in rule conditions. Possible types include: + - "string": Text value. + - "number": Numerical value. + - "boolean": True or false. + - "date": Date value. + - "reference": A reference to an external identifier, often used with options-type fields to indicate that the value is an ID or a unique attribute from related data." + enum: + - string + - number + - boolean + - date + - reference + valueReferenceAttribute: + type: string + description: "The key attribute in the options data (e.g., 'id') used to represent the option's selected value in rule expressions. Only available when 'valueType' is 'reference'." + example: id + valueDisplayAttribute: + type: string + description: "The attribute to show as the label for each option in the dropdown (e.g., 'name') when listing options. Only available when 'valueType' is 'reference'." + example: name + links: + type: array + description: Endpoints to retrieve or search for options dynamically. Included only when 'valueType' is 'reference'. + example: + - href: /scim2/roles?offset=0&limit=10 + method: GET + rel: values + - href: /scim2/roles/.search + method: GET + rel: filter + items: + $ref: '#/components/schemas/Link' + values: + type: array + description: "List of selectable values for options fields when 'valueType' is 'string', 'number', 'boolean', or 'date'." + items: + $ref: '#/components/schemas/ValueObject' + Operator: + type: object + properties: + name: + type: string + description: Name of the operator. The immutable identifier of the operator referenced within the rule expression. + displayName: + type: string + description: Display name of the operator. Use as a user friendly label of the operator to show in UI. + ValueObject: + type: object + properties: + name: + type: string + description: The name that uniquely identifies the option. + displayName: + type: string + description: The display name for the option. + Link: + type: object + properties: + href: + type: string + description: Url of the endpoint. + method: + type: string + description: Http method. + enum: + - GET + rel: + type: string + description: Indicates the endpoint’s relation to retrieving or filtering field values. + enum: + - values + - filter + Error: + type: object + properties: + code: + type: string + description: Error code + example: RMS-00000 + message: + type: string + description: Error message. + example: Some error message. + description: + type: string + description: Detailed error description. + example: Some error description. + traceId: + type: string + description: Trace identifier to refer at troubleshooting logs to troubleshoot the problem. + example: e0fbcfeb-3617-43c4-8dd0-7b7d38e13047 + securitySchemes: + OAuth2: + type: oauth2 + flows: + authorizationCode: + authorizationUrl: 'https://api.asgardeo.io/t/{org-name}/oauth2/authorize' + tokenUrl: 'https://api.asgardeo.io/t/{org-name}/oauth2/token' + scopes: + read: internal_rule_metadata_view diff --git a/en/asgardeo/docs/apis/rule-metadata-rest-api.md b/en/asgardeo/docs/apis/rule-metadata-rest-api.md new file mode 100644 index 0000000000..3ead0563dd --- /dev/null +++ b/en/asgardeo/docs/apis/rule-metadata-rest-api.md @@ -0,0 +1,5 @@ +--- +template: templates/redoc.html +--- + + \ No newline at end of file diff --git a/en/asgardeo/docs/complete-guides/angular/accessing-protected-api.md b/en/asgardeo/docs/complete-guides/angular/accessing-protected-api.md new file mode 100644 index 0000000000..0efd4cbb2d --- /dev/null +++ b/en/asgardeo/docs/complete-guides/angular/accessing-protected-api.md @@ -0,0 +1,109 @@ +--- +template: templates/complete-guide.html +heading: Accessing protected API from your Angular app +read_time: 2 min +--- + +We’ve covered most of the key activities for adding user login to your Angular app. To recap, during user login, the Angular OAuth2 OIDC SDK provides both an ID token and an access token. We’ve been using the ID token in the previous sections to establish the logged-in user context and enable secure access. In this section, we’ll focus on how to call a secure API from your Angular app using the other token—the access token. + +For simplicity, let's assume that the APIs we’re calling are secured by the same Identity Provider (IdP) and use the same issuer— in this case, the same Asgardeo organization. This is typical when Angular apps are interacting with internal APIs within the same organization. However, if your app needs to call APIs secured by a different IdP, you’ll need to exchange your current access token for a new one issued by the IdP securing those APIs. This can be done using the OAuth2 token exchange grant type or other supported grant types. We will cover these scenarios in a separate guide. + +## Using SDK Built-in HTTP client + +You can utilize Angular's `HttpClient` to make HTTP requests to secure endpoints. You don't need to manually attach the access token to requests if you use the Angular OAuth2 OIDC SDK correctly, as it will handle that automatically. +The following is a simple example of how you might use the Angular OAuth2 OIDC SDK’s `HttpClient` to call a protected API endpoint, such as `/scim2/me` (to get the user profile details after signing in). In this case, the SCIM 2 endpoint is secured by the same Asgardeo organization. Asgardeo provides a SCIM 2 API for managing users within your organization. While user management with SCIM 2 is a topic for a different guide, we will use the API as part of our current guide. + +### Step 1: Import Required Modules + +Update the `app.config.ts` file as follows to configure the allowed URLs and include the access token in API requests. Ensure you refer to the domains of your API server under `allowedUrls` and set `sendAccessToken` to `true` so that the access token is included in the requests made to these endpoints: + + +```javascript title="src/main.jsx" hl_lines="5-11" +import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http'; + +export const appConfig: ApplicationConfig = { + providers: [provideRouter(routes), + provideHttpClient(withInterceptorsFromDi()), + provideOAuthClient({ + resourceServer: { + allowedUrls: ['https://api.asgardeo.io'], + sendAccessToken: true + } + }), + { + provide: APP_INITIALIZER, + useFactory: initializeOAuth, + deps: [OAuthService], + multi: true + } + ] +}; + +``` + + +### Step 2: Make HTTP Requests + +In your component, you can use Angular's `HttpClient` to call secure APIs. Here's how to do it: + +```javascript title="src/main.jsx" hl_lines="16" + +import { Component, inject } from '@angular/core'; +import { HttpClient } from '@angular/common/http'; + +@Component({ + selector: 'app-dashboard', + standalone: true, + imports: [], + templateUrl: './dashboard.component.html', + styleUrl: './dashboard.component.css' +}) +export class DashboardComponent { + private http = inject(HttpClient); + data: any; + + constructor() { + this.http.get('https://api.asgardeo.io/t/mifrazmurthaja/scim2/Me') + .subscribe(response => this.data = response); + } +} + + +``` + +In the above code, the access token is automatically attached to the `Authorization` header by the Angular OAuth2 OIDC SDK when you make requests to the specified allowed URLs. + + +## Manually Managing Access Tokens in API Requests + +If you are not using the built-in access token management, you can manually fetch the access token and attach it to your requests. Here’s how to do that: + + +```javascript title="src/main.jsx" + +import { Component, inject } from '@angular/core'; +import { HttpClient, HttpHeaders } from '@angular/common/http'; +import { OAuthService } from 'angular-oauth2-oidc'; + +@Component({ + selector: 'app-dashboard', + standalone: true, + imports: [], + templateUrl: './dashboard.component.html', + styleUrl: './dashboard.component.css' +}) +export class DashboardComponent { + private http = inject(HttpClient); + data: any; + + constructor(private oAuthService : OAuthService) { + const token = this.oAuthService.getAccessToken(); + const headers = new HttpHeaders().set('Authorization', `Bearer ${token}`); + this.http.get('https://api.asgardeo.io/t/mifrazmurthaja/scim2/Me', { headers }) + .subscribe(response => this.data = response); + } +} + + + +``` \ No newline at end of file diff --git a/en/asgardeo/docs/complete-guides/angular/add-login-and-logout.md b/en/asgardeo/docs/complete-guides/angular/add-login-and-logout.md new file mode 100644 index 0000000000..af3aefebfc --- /dev/null +++ b/en/asgardeo/docs/complete-guides/angular/add-login-and-logout.md @@ -0,0 +1,99 @@ +--- +template: templates/complete-guide.html +heading: Add login and logout to your app +read_time: 2 min +--- + +Next, let's add login and logout features to your Angular app. Angular uses services to access authentication data, and we can inject the `OAuthService` into your components to manage user authentication. The `OAuthService` provides methods for logging in and out, checking the user's authentication status, and retrieving access tokens. The key methods you will use are `initLoginFlow()` for signing in and `revokeTokenAndLogout()` for signing out. You can use these methods directly within your Angular components to trigger login and logout actions. + +Replace the existing content of the `app.component.ts` file with following content. + +!!! tip + For better organization, you can create separate components for different purposes, such as login and home pages. However, for simplicity, we are using the default component in this example. + +```javascript title="app.component.ts" hl_lines="16-28" + +import { Component } from '@angular/core'; +import { RouterOutlet } from '@angular/router'; +import { OAuthService } from 'angular-oauth2-oidc'; +import { CommonModule } from '@angular/common'; + +@Component({ + selector: 'app-root', + standalone: true, + imports: [RouterOutlet, CommonModule], + templateUrl: './app.component.html', + styleUrl: './app.component.css' +}) + +export class AppComponent { + title = 'asgardeo-angular'; + isAuthorized = this.oAuthService.hasValidAccessToken(); + + constructor(private oAuthService: OAuthService) { + + } + + login() { + this.oAuthService.initLoginFlow(); + } + + logout() { + this.oAuthService.revokeTokenAndLogout(); + } +} + +``` + +Once you've defined these methods in app.component.ts, update the corresponding HTML template in app.component.html by modifying the lines below: + +```html title="app.component.html" + + + + + +``` + +Let’s look into the underlying details of what’s happening here. + +The `AppComponent` leverages the `OAuthService`, which was initialized earlier in the `ApplicationConfig` using `authConfig`, to access various methods and attributes provided by the SDK, such as `initLoginFlow()`, `revokeTokenAndLogout()`, and user-specific attributes. The `AppComponent` defines its own methods, like `login()` and `logout()`, which make use of these SDK methods. + +In `app.component.html`, these methods are tied to button click events. The template also dynamically renders content based on the user's authentication status. It checks for the presence of the username attribute in the session to determine if the user is authenticated. If username is available, indicating that the user is logged in, the "Logout" button is displayed and triggers the `logout()` method. Otherwise, the "Login" button is shown, which initiates the login process via `login()`. + +Save the changes and re-run the application. + +```bash +ng serve + +``` + +Visit your app's homepage at [http://localhost:4200](http://localhost:4200). + + +## Initiate Sign In +Clicking on the login button will initiate an OIDC request. You can observe this authorization request in the browser's DevTools. To do so, right-click on the application, click "Inspect," switch to the "Network" tab, and in the filter input, type "authorize." Then, click on the Login button to see the details of the request. + +![OIDC request]({{base_path}}/complete-guides/angular/assets/img/image15.png){: width="800" style="display: block; margin: 0;"} + +!!! tip "Tip" + + The OpenID Connect specification offers several functions, known as grant types, to obtain an access token in exchange for user credentials. This example uses the authorization code grant type. In this process, the app first requests a unique code from the authentication server, which can later be used to obtain an access token. For more details on the authorization code grant type, please refer to the [Asgardeo documentation.](https://wso2.com/asgardeo/docs/guides/authentication/oidc/implement-auth-code-with-pkce/){:target="_blank"} + +Asgardeo will receive this authorization request and respond by redirecting the user to a login page to enter their credentials. + +![OIDC request]({{base_path}}/complete-guides/angular/assets/img/image16.png){: width="800" style="display: block; margin: 0;"} + +At this stage, **you need to create a [test user in Asgardeo](https://wso2.com/asgardeo/docs/guides/users/manage-users/#onboard-users){:target="_blank"} to try out the application.** Once you create a test user, you can enter the username and password of the test user to the login screen. + +!!! tip "Tip" + + **PKCE (Proof Key for Code Exchange)** is an addition to the OAuth2 specification to make the authorization code more immune to replay attacks. It is enabled by default for public clients such as our single page Angular app. + + If you want to disable PKCE for some reason, you can do so via following the steps below. **However, disabling PKCE for public clients such as our single page Angular app is highly discouraged.** + + 1. Log in to the {{product_name}} console and select the application you created. + 2. Switch to the Protocol tab. + 3. Uncheck the Mandatory checkbox under PKCE section. + +In this section, we have added login and logout features to our Angular app. In the next step, we will look into how to access the user attributes of the logged in user. diff --git a/en/asgardeo/docs/complete-guides/angular/assets/img/image15.png b/en/asgardeo/docs/complete-guides/angular/assets/img/image15.png new file mode 100644 index 0000000000..1b44db387c Binary files /dev/null and b/en/asgardeo/docs/complete-guides/angular/assets/img/image15.png differ diff --git a/en/asgardeo/docs/complete-guides/angular/assets/img/image16.png b/en/asgardeo/docs/complete-guides/angular/assets/img/image16.png new file mode 100644 index 0000000000..3c01602b1b Binary files /dev/null and b/en/asgardeo/docs/complete-guides/angular/assets/img/image16.png differ diff --git a/en/asgardeo/docs/complete-guides/angular/assets/img/image5.png b/en/asgardeo/docs/complete-guides/angular/assets/img/image5.png new file mode 100644 index 0000000000..5fd6c72c07 Binary files /dev/null and b/en/asgardeo/docs/complete-guides/angular/assets/img/image5.png differ diff --git a/en/asgardeo/docs/complete-guides/angular/assets/img/image6.png b/en/asgardeo/docs/complete-guides/angular/assets/img/image6.png new file mode 100644 index 0000000000..eea3f0c296 Binary files /dev/null and b/en/asgardeo/docs/complete-guides/angular/assets/img/image6.png differ diff --git a/en/asgardeo/docs/complete-guides/angular/assets/img/image8.png b/en/asgardeo/docs/complete-guides/angular/assets/img/image8.png new file mode 100644 index 0000000000..e10051c0ad Binary files /dev/null and b/en/asgardeo/docs/complete-guides/angular/assets/img/image8.png differ diff --git a/en/asgardeo/docs/complete-guides/angular/create-app.md b/en/asgardeo/docs/complete-guides/angular/create-app.md new file mode 100644 index 0000000000..f684ec3eb9 --- /dev/null +++ b/en/asgardeo/docs/complete-guides/angular/create-app.md @@ -0,0 +1,45 @@ +--- +template: templates/complete-guide.html +heading: Create an Angular app +read_time: 2 min +--- + +For this guide, you will be creating a simple Angular app using Angular CLI, the official tool provided by Angular to simplify project scaffolding and development. + +!!! note + + The Angular OAuth2 OIDC SDK supports only up to Angular CLI version 17. Therefore, we are creating this application using Angular CLI version 17. + + +Open a terminal, change the directory to where you want to initialize the project, and run the following command to create your first Angular sample application + + +```bash +npm install -g @angular/cli@17 + +ng new asgardeo-angular +``` + +Running this command will create a folder with a ready-made Angular application. + +Once the application is created, install the necessary dependencies using the following command: + + +```bash + +cd asgardeo-angular + +npm install +``` + +Then run the sample in the development mode. This allows you to see real-time updates and debug the app as you make changes. + +```bash +ng serve +``` + +By default, the development server will run on the port 4200. You can navigate to [http://localhost:4200](http://localhost:4200){:target="_blank"} in your browser, and you should see the sample application working as expected. + +![Navigate to localhost]({{base_path}}/complete-guides/angular/assets/img/image6.png){: width="600" style="display: block; margin: 0;"} + +At this point, you have a simple yet fully functional Angular app. In the next step, let’s try to integrate an authentication SDK with the app. diff --git a/en/asgardeo/docs/complete-guides/angular/display-logged-in-user-details.md b/en/asgardeo/docs/complete-guides/angular/display-logged-in-user-details.md new file mode 100644 index 0000000000..3da0d9b031 --- /dev/null +++ b/en/asgardeo/docs/complete-guides/angular/display-logged-in-user-details.md @@ -0,0 +1,76 @@ +--- +template: templates/complete-guide.html +heading: Display logged-in user details +read_time: 2 min +--- + +At this point, we’ve successfully implemented login and logout capabilities by integrating your Angular app with {{product_name}}. The next step is to access and display the logged-in user details within the application. The SDK provides a way to retrieve the authenticated user’s basic information. + +To do this, you can leverage the `getIdentityClaims` method to fetch the user’s profile information. The following code example demonstrates how to access and display the user's profile information in your Angular component. + +Add the `username()` function to the `app.component.ts` file to access the username attribute. + +```javascript title="app.component.ts" + + + get username() { + var claims = this.oAuthService.getIdentityClaims(); + if (!claims) return null; + return claims['username']; + } + + +``` + + +Next, modify the `app.component.html` file with the following code. + +```html title="app.component.html" hl_lines="2" + + +

Hello {{ username }}!

+ + +``` + + +## Getting additional user attributes + +In the above code, we have rendered only the username of the logged-in user. Similarly, you can access other user attributes, such as given_name and and country. The following code snippet illustrates how to access these attributes in your app. The Angular OAuth2 OIDC SDK is responsible for processing the ID token and decoding these attributes. + +1. Log in to the {{product_name}} console and select the application you created. +2. Go to the **User Attributes** tab. +3. Select the **given_name** attribute. +4. Click Update to save the changes. + +Add the `username()` function to the `app.component.ts` file to access the username attribute. + +```javascript title="app.component.ts" hl_lines="7-11" + get username() { + var claims = this.oAuthService.getIdentityClaims(); + if (!claims) return null; + return claims['username']; + } + + get givenName() { + var claims = this.oAuthService.getIdentityClaims(); + if (!claims) return null; + return claims['given_name']; + } + +``` + + +Now, we can display the given_name attribute by modify the `app.component.html` file with the following code. + +```html title="app.component.html" hl_lines="3" + + +

Hello {{ username }}!

+

Your given name : {{ givenName }}!

+ + +``` + + +In this step, we further improved our Angular app to display the user attributes. As the next step, we will try to secure routes within the app. diff --git a/en/asgardeo/docs/complete-guides/angular/install-asgardeo-sdk.md b/en/asgardeo/docs/complete-guides/angular/install-asgardeo-sdk.md new file mode 100644 index 0000000000..70dcd2394a --- /dev/null +++ b/en/asgardeo/docs/complete-guides/angular/install-asgardeo-sdk.md @@ -0,0 +1,96 @@ +--- +template: templates/complete-guide.html +heading: Install and configure Asgardeo SDK +read_time: 2 min +--- + +## Install authentication SDK + +The [Angular OAuth2 OIDC SDK](https://github.com/manfredsteyer/angular-oauth2-oidc/){:target="_blank"} is a production-ready authentication SDK that simplifies integrating Asgardeo with your Angular applications. It provides key features such as user authentication, retrieving user information, and automatically attaching tokens to HTTP requests for secure API communication. + +Next, change your current directory to the project folder and run the following command to install the Angular OAuth2 OIDC SDK from the npm registry. + +```bash + npm install angular-oauth2-oidc + +``` + +## Add `AuthConfig` to your app + +In the previous step, you added the Angular OAuth2 OIDC SDK as a dependency in your app. Now, we will configure the `AuthConfig` to set up authentication using Asgardeo. The `OAuthService` provided by the SDK will handle authentication throughout the application. You can configure the authentication service by providing the necessary OIDC settings like the `client_id`, `issuer`, and `redirect URIs`. These configurations allow your Angular app to communicate with Asgardeo for user authentication. + +In the `app.config.ts` file, you can import the `OAuthService` from the SDK. This corresponds to [Option 1](https://github.com/manfredsteyer/angular-oauth2-oidc?tab=readme-ov-file#option-1-standalone-apis){:target="_blank"} indicated in the Angular OIDC SDK, which utilizes Standalone Components introduced with Angular 14. You can set up the OAuth client using the standalone API of the SDK by calling `provideOAuthClient()`. Next, configure the `AuthConfig` with your Asgardeo application details. + + +Replace the content of `app.config.ts` file with the following code. + +!!! Important + + Make sure to replace the placeholders in the following code with the **`client-id`** and **`issuer`** values you copied in **Step-3** during the application registration in the {{product_name}} console. + + - `` + - `` + + +```javascript title="app.config.ts" + +import { ApplicationConfig, APP_INITIALIZER } from '@angular/core'; +import { provideRouter } from '@angular/router'; +import { provideHttpClient } from '@angular/common/http'; +import { provideOAuthClient, OAuthService, AuthConfig } from 'angular-oauth2-oidc'; +import { routes } from './app.routes'; + +export const authConfig: AuthConfig = { + issuer: '', + redirectUri: 'http://localhost:4200', + clientId: '', + responseType: 'code', + scope: 'openid profile email internal_login', + strictDiscoveryDocumentValidation: false, +}; + +function initializeOAuth(oauthService: OAuthService): () => Promise { + return () => { + oauthService.configure(authConfig); + return oauthService.loadDiscoveryDocumentAndTryLogin().then(() => { }); + }; +} + +export const appConfig: ApplicationConfig = { + providers: [provideRouter(routes), + provideHttpClient(), + provideOAuthClient(), + { + provide: APP_INITIALIZER, + useFactory: initializeOAuth, + deps: [OAuthService], + multi: true + } + ] +}; + + +``` + +!!! Important + + Make sure to add **`strictDiscoveryDocumentValidation: false`** parameter. The configuration parameter `strictDiscoveryDocumentValidation` is set to `true` by default. This ensures that all endpoints provided in the Identity Provider discovery document share the same base URL as the issuer parameter. However, several Identity Providers, including Asgardeo, may use different domains or path parameters for various endpoints in the discovery document. While these providers may still comply with the OpenID Connect Provider Configuration specification, they will fail this library's discovery document validation. To resolve this, you need to set `strictDiscoveryDocumentValidation` to `false` + + + + +As shown above, we configure authentication at the root level of the Angular application to ensure that all components can interact with the authentication logic provided by Asgardeo. This is achieved by passing a configuration object, `authConfig` to the `OAuthService` with the following values, which are defined in the Asgardeo console. The `authConfig` object holds the configuration necessary for connecting the app to Asgardeo. It includes properties like `redirectUri`, which determine where users are redirected after signing in or out. The `clientID` identifies the application, and issuer specifies the Asgardeo token API endpoint specific to your organization, which is used to obtain the discovery document by the SDK. The scope array lists the OAuth2.0 permissions the app requires, such as `openid` and `profile`. + + +The following table provide a summery of the important configuration parameters. + +| **Parameter** | **Description** | **Example** | +|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------| +| `redirectUri` | The URL to redirect the user to after successfully signing in. This URL should be an absolute URL and only accessible to authenticated users. | `http://localhost:4200` | +| `clientId` | The client ID of the created OIDC application. | | +| `issuer` | The issuer name of the Identity Provider, used by the SDK to obtain the discovery document by invoking the OIDC discovery endpoint at `/.well-known/openid-configuration`. For Asgardeo, this is the same as the token endpoint. | `https://api.asgardeo.io/t//oauth2/token` | +| `scope` | Specifies the required application scopes as a list. In this guide, we request the 'profile' scope for access to user details. | `[ "openid profile" ]` | + +!!! Important + + Since your Angular app is classified as a public client according to OAuth2 specifications (as it runs on user devices and cannot securely store credentials), no client secret is involved. Public clients cannot securely store credentials, so Identity Providers should not authenticate public clients before issuing access tokens. The Angular OAuth2 OIDC SDK addresses this by using the **PKCE (Proof Key for Code Exchange)** extension to mitigate security risks associated with public clients. \ No newline at end of file diff --git a/en/asgardeo/docs/complete-guides/angular/introduction.md b/en/asgardeo/docs/complete-guides/angular/introduction.md new file mode 100644 index 0000000000..4ccf4587bb --- /dev/null +++ b/en/asgardeo/docs/complete-guides/angular/introduction.md @@ -0,0 +1,30 @@ +--- +template: templates/complete-guide.html +heading: Introduction +read_time: 2 mins +--- + +Angular is a widely-used front-end framework built on TypeScript, designed for creating robust single-page applications (SPAs). It offers a structured and modular approach to building dynamic UIs, making it easier for developers to manage complex applications by breaking them down into reusable components. Angular’s two-way data binding and dependency injection, coupled with its component-based architecture, streamline UI updates without requiring the entire page to reload. This makes Angular a popular choice for developing SPAs. +Implementing login in your Angular app is essential for managing user access, personalizing user experiences, and ensuring app security. It improves user experience, secures user data, increases engagement, and helps meet regulatory compliance. + +## Learning objectives + +This guide will walk you through everything you need to know about securing Angular apps, including implementing user login in your Angular app, integrating it with an Identity Provider (IdP) to make the login process simple and secure, and general guidelines to protect your end users. It also covers how to make secure API calls to an OAuth2-protected API within your Angular app. + +In this guide, you will: + +* Register an application in {{product_name}} +* Create a Angular app +* Install Authentication SDK into the app +* Add login and logout to your app +* Display logged in user detail +* Securing routes within the app +* Accessing protected API from your Angular app +* Managing tokens in your Angular app + + +!!! tip "Tip" + + This guide takes approximately 60 minutes to complete and covers everything required to add user login and secure your Angular apps. If you’re looking for a shorter guide, try the [Angular Quick Start guide](https://wso2.com/asgardeo/docs/quick-starts/angular/){:target="_blank"}, which takes around 15 minutes to complete. + + diff --git a/en/asgardeo/docs/complete-guides/angular/manage-tokens.md b/en/asgardeo/docs/complete-guides/angular/manage-tokens.md new file mode 100644 index 0000000000..0d24756bb5 --- /dev/null +++ b/en/asgardeo/docs/complete-guides/angular/manage-tokens.md @@ -0,0 +1,73 @@ +--- +template: templates/complete-guide.html +heading: Manage tokens in Angular apps +read_time: 2 min +--- + +## Token Validation + +A key principle of security tokens is that the receiver must first validate the token. This involves checking the authenticity of the token issuer, ensuring the token meets validity criteria such as expiration time, and confirming that the receiver is authorized to use the token. The Angular OAuth2 OIDC SDK handles token validation as part of its authentication process, ensuring that users hold valid and unexpired tokens before accessing protected resources. + +When a user signs in, the SDK acquires an access token and an ID token from the identity provider. The access token is a UUID, which requires an API call to the IdP for validation. On the other hand, the ID token is a JSON Web Token (JWT), and the SDK automatically validates it by performing the following checks: + +- **Signature Validation:** The SDK verifies the JWT's signature using the public key retrieved from the identity provider's JWKS endpoint. This ensures the token has been issued by a trusted authority and hasn’t been tampered with. + +- **Expiration Check:** The SDK checks the exp (expiration) claim to ensure the token is still valid. If the token has expired, it is considered invalid. + +- **Issuer Validation:** The iss (issuer) claim in the token is validated against the configured issuer URL. This ensures the token came from the expected identity provider. + +- **Audience Validation:** The SDK checks the aud (audience) claim to confirm that the token is meant for your application, identified by the clientId. + +## Token Persistence + +In the Angular OAuth2 OIDC SDK, the storage mechanism determines where the authentication state, tokens, and related data are stored. By default, the SDK uses `sessionStorage` for token persistence, but it also allows you to configure it to use `localStorage` or other custom storage mechanisms. + +You can specify the storage mechanism in the OAuthService configuration by invoking the setStorage method in app.config.ts. Here's how you can configure it for different storage types. + +- **Local Storage:** localStorage stores data across browser sessions, meaning the data persists even after the browser is closed and reopened. + +```javascript + +function initializeOAuth(oauthService: OAuthService): () => Promise { + return () => { + oauthService.configure(authConfig); + oauthService.setStorage(localStorage); + return oauthService.loadDiscoveryDocumentAndTryLogin().then(() => {}); + }; +} + + +``` + +- **Session Storage:** sessionStorage stores data for the duration of the page session. The data is cleared when the page session ends (e.g., when the tab is closed). + +```javascript + +function initializeOAuth(oauthService: OAuthService): () => Promise { + return () => { + oauthService.configure(authConfig); + oauthService.setStorage(sessionStorage); + return oauthService.loadDiscoveryDocumentAndTryLogin().then(() => {}); + }; +} + + + +``` + +- **Custom Storage:** You can define a custom storage mechanism for handling token persistence, such as using a secure web worker. To implement a custom storage solution, you can extend the OAuthStorage class, following the guidance provided in the [documentation](https://manfredsteyer.github.io/angular-oauth2-oidc/docs/classes/OAuthStorage.html#info){:target="_blank"}. + + +## Initiate Logout + +The Angular OAuth2 OIDC SDK provides a straightforward approach to handle user logout in your application. When a user logs out, the SDK ensures that both the local session and the session on the identity provider are terminated, providing a complete and secure logout process without requiring manual cleanup activities. + +When a user initiates logout, the following steps typically occur: + +- **Local Session Termination:** The SDK clears any locally stored credentials, such as the access token and ID token, which are essential for maintaining the user's authentication state within the application. This effectively logs the user out of the application locally. + +- **Redirection to Identity Provider for Sign Out:** After clearing the local session, the SDK redirects the user to the sign-out endpoint of your identity provider (in this case, Asgardeo). This ensures that the user is also signed out globally from Asgardeo. This step is especially important in single sign-on (SSO) scenarios where the user may be logged into multiple applications under the same identity. + +- **Post Sign-Out Redirection:** Once the global sign-out process is complete, the user is redirected back to a specified URL, which is usually the application's homepage or a custom logout page. This URL can be configured in the SDK's `authConfig` under the `postLogoutRedirectUri`. + + diff --git a/en/asgardeo/docs/complete-guides/angular/next-steps.md b/en/asgardeo/docs/complete-guides/angular/next-steps.md new file mode 100644 index 0000000000..4cbab27293 --- /dev/null +++ b/en/asgardeo/docs/complete-guides/angular/next-steps.md @@ -0,0 +1,13 @@ +--- +template: templates/complete-guide.html +heading: Next Steps +read_time: 1 min +--- +This guide you just have completed, covered the adding user login for Angular apps by integrating with an Identity Provider (IdP) and additional use cases such making calls to an OAuth2-protected API. + +Now that your Angular application is secured with authentication features integrated, It is time to explore the additional features {{product_name}} offers to make the login flow more diverse and secure. + +- [Multi factor authentication](https://wso2.com/asgardeo/docs/guides/authentication/mfa/){:target="_blank"} +- [Passwordless authentication](https://wso2.com/asgardeo/docs/guides/authentication/passwordless-login/){:target="_blank"} +- [Self registration](https://wso2.com/asgardeo/docs/guides/user-accounts/configure-self-registration/){:target="_blank"} +- [Login UI customization](https://wso2.com/asgardeo/docs/guides/branding/){:target="_blank"} diff --git a/en/asgardeo/docs/complete-guides/angular/prerequisite.md b/en/asgardeo/docs/complete-guides/angular/prerequisite.md new file mode 100644 index 0000000000..c44df2cb30 --- /dev/null +++ b/en/asgardeo/docs/complete-guides/angular/prerequisite.md @@ -0,0 +1,19 @@ +--- +template: templates/complete-guide.html +heading: Prerequisite +read_time: 30 secs +--- + +## Before you start, ensure you have the following: + +* About 60 minutes +* {{product_name}} account +* [Node.js](https://nodejs.org/en/download/package-manager){:target="_blank"} v18+ and npm +* Install Angular CLI +* A favorite text editor or IDE + + +!!! note "Note" + + You need to have installed [Node.js](https://nodejs.org/en/download/package-manager){:target="_blank"} v18+ and npm (which comes inbuilt with Node) to run this sample. Although Node.js is primarily a server-side language,it needs to have been installed to manage dependencies and run scripts for our project. + diff --git a/en/asgardeo/docs/complete-guides/angular/register-an-application.md b/en/asgardeo/docs/complete-guides/angular/register-an-application.md new file mode 100644 index 0000000000..206de6ebfe --- /dev/null +++ b/en/asgardeo/docs/complete-guides/angular/register-an-application.md @@ -0,0 +1,34 @@ +--- +template: templates/complete-guide.html +heading: Register an application in Asgardeo +read_time: 2 min +--- + +First unless you already have done that, you need to create an organization in {{product_name}} and register your application as a single page application. + +* Sign up for a [free {{product_name}} account](https://wso2.com/asgardeo/docs/get-started/create-asgardeo-account/){:target="_blank"} +* Sign into {{product_name}} console and navigate to **Applications > New Application.** +* Select **Single Page Application** + +![Select Single Page Application]({{base_path}}/complete-guides/angular/assets/img/image5.png){: width="600" style="display: block; margin: 0;"} + +Next, complete the wizard popup by providing a suitable name and an authorized redirect URL. + +!!! Example + name: asgardeo-angular + + Authorized redirect URL: http://localhost:4200 + +![Register a new application]({{base_path}}/complete-guides/angular/assets/img/image8.png){: width="600" style="display: block; margin: 0;"} + +!!! Info + + The authorized redirect URL determines where {{product_name}} should send users after they successfully log in. Typically, this will be the web address where your app is hosted. For this guide, we'll use [http://localhost:4200](http://localhost:4200){:target="_blank"}, as the sample app will be accessible at this URL. + +Make a note of the following values from the **Protocol** and **Info** tabs of the registered application. You will need them to configure the authentication SDK + +- **`client-id`** from the **Protocol** tab. +- **`issuer`** from from the **Info** tab. + + +In this step, we have ve registered our Angular app as an application in the {{product_name}} console and generated the required metadata. Next, we will create a Angular app. diff --git a/en/asgardeo/docs/complete-guides/angular/securing-routes-within-the-app.md b/en/asgardeo/docs/complete-guides/angular/securing-routes-within-the-app.md new file mode 100644 index 0000000000..2e4d581e63 --- /dev/null +++ b/en/asgardeo/docs/complete-guides/angular/securing-routes-within-the-app.md @@ -0,0 +1,75 @@ +--- +template: templates/complete-guide.html +heading: Securing Routes within the app +read_time: 2 min +--- + +In an Angular application, routes define the paths that users can navigate to, linking URLs to specific components. Securing routes is essential to protect sensitive data, prevent unauthorized access, and ensure that only authenticated users can access certain parts of the application. In this section, we will explore how to secure routes using the angular-oauth2-oidc library. + +In Angular, route guards are used to control access to certain routes. You can implement a route guard that checks whether a user is authenticated before allowing access to specific routes. + +#### Step 1: Create an Auth Guard + +Create an Auth Guard using Angular CLI: + +```bash +ng generate guard auth +``` + +The above command generates an `auth.guard.ts` file, and update this file with the following content. + +```javascript title="auth.guard.ts" +import { inject } from '@angular/core'; +import { CanActivateFn, Router } from '@angular/router'; +import { OAuthService } from 'angular-oauth2-oidc'; + +export const authGuard: CanActivateFn = (route, state) => { + + const oAuthService = inject(OAuthService); + const router = inject(Router); + + if (oAuthService.hasValidAccessToken()) { + return true; + } else { + // Redirect to login if not authenticated + router.navigate(['/login']); + return false; + } +}; + +``` + + + +#### Step 2: Define Routes + +Next, define your routes in `app-routing.module.ts` and apply the AuthGuard to secure specific routes. + +```javascript title="app-routing.module.ts" + +import { Routes } from '@angular/router'; +import { AppComponent } from './app.component'; +import { DashboardComponent } from './dashboard/dashboard.component'; +import { LoginComponent } from './login/login.component'; +import { authGuard } from './auth.guard'; + +export const routes: Routes = [ + { path: '', component: AppComponent }, + { path: 'dashboard', component: DashboardComponent, canActivate: [authGuard] }, + { path: 'login', component: LoginComponent }, + { path: '**', redirectTo: '' } // Redirect any unknown paths to home +]; + + +``` + +The above route definition assumes that you have created components in your application such as `dashboard`. You can create new components a using Angular CLI. The following example code shows how you can create a components called `dashboard`. + +```bash +ng generate component dashboard +``` + +The `AuthGuard` checks if the user has a valid access token. If not, it redirects the user to the login page. You can customize the logic inside the canActivate method to include additional checks or redirect logic as necessary. + + + diff --git a/en/asgardeo/docs/quick-starts/angular.md b/en/asgardeo/docs/quick-starts/angular.md index d503a503ce..682f47fa2d 100644 --- a/en/asgardeo/docs/quick-starts/angular.md +++ b/en/asgardeo/docs/quick-starts/angular.md @@ -238,7 +238,7 @@ Modified the code as below to see logged in user details. Add the `username()` function to the `app.component.ts` file to access the username attribute. ```javascript title="app.component.ts" hl_lines="3-6" -... + get username() { var claims = this.oAuthService.getIdentityClaims(); @@ -246,7 +246,7 @@ Add the `username()` function to the `app.component.ts` file to access the usern return claims['username']; } -... + ``` Modify the `app.component.html` file with the following code. diff --git a/en/asgardeo/docs/quick-starts/react.md b/en/asgardeo/docs/quick-starts/react.md index dbb521092d..85ac959d77 100644 --- a/en/asgardeo/docs/quick-starts/react.md +++ b/en/asgardeo/docs/quick-starts/react.md @@ -4,13 +4,14 @@ heading: React Quickstart description: Welcome to the React Quickstart guide! In this document, you will learn to build a React app, add user login and display user profile information using Asgardeo. what_you_will_learn: - Create new React app using Vite - - Install @asgardeo/auth-react package + - Install @asgardeo/auth-react package - Add user login and logout - Display user profile information prerequisites: - About 15 minutes - Asgardeo account - - Install a JS package manager + - Install Node.js on your system. + - Make sure you have a JavaScript package manager like npm, yarn, or pnpm. - A favorite text editor or IDE source_code: React Vite App Sample whats_next: @@ -44,7 +45,7 @@ Create (a.k.a scaffold) your new React app using Vite. === "npm" - ``` bash + ```bash npm create vite@latest asgardeo-react -- --template react cd asgardeo-react @@ -56,26 +57,26 @@ Create (a.k.a scaffold) your new React app using Vite. === "yarn" - ``` bash + ```bash yarn create vite@latest asgardeo-react -- --template react cd asgardeo-react - yran install + yarn install yarn dev ``` === "pnpm" - ``` bash + ```bash pnpm create vite@latest asgardeo-react -- --template react cd asgardeo-react pnpm install - pnpm run dev + pnpm dev ``` ## Install @asgardeo/auth-react @@ -84,19 +85,19 @@ Asgardeo React SDK provides all the components and hooks you need to integrate A === "npm" - ``` bash + ```bash npm install @asgardeo/auth-react ``` === "yarn" - ``` bash + ```bash yarn add @asgardeo/auth-react ``` === "pnpm" - ``` bash + ```bash pnpm add @asgardeo/auth-react ``` @@ -113,29 +114,28 @@ Add the following changes to the `main.jsx` file. - `` - `https://api.asgardeo.io/t/` -```javascript -import React from 'react'; -import ReactDOM from 'react-dom/client'; -import App from './App.jsx'; -import { AuthProvider } from '@asgardeo/auth-react'; -import './index.css'; - -const config = { - signInRedirectURL: "http://localhost:5173", - signOutRedirectURL: "http://localhost:5173", - clientID: "", - baseUrl: "https://api.asgardeo.io/t/", - scope: [ "openid","profile" ] -} - -ReactDOM.createRoot(document.getElementById('root')).render( - - - - - , -); - +```javascript hl_lines="5 9-17 19" +import { StrictMode } from 'react' +import { createRoot } from 'react-dom/client' +import './index.css' +import App from './App.jsx' +import { AuthProvider } from '@asgardeo/auth-react' + +createRoot(document.getElementById('root')).render( + + ', + baseUrl: 'https://api.asgardeo.io/t/', + scope: ['openid', 'profile'], + } } + > + + + +) ``` ## Add login and logout link to your app @@ -144,25 +144,25 @@ Asgardeo provides `useAuthContext` hook to conveniently access user authenticati Replace the existing content of the `App.jsx` file with following content. -```javascript -import { useAuthContext } from "@asgardeo/auth-react"; -import './App.css'; +```javascript hl_lines="1 5 9-13" +import { useAuthContext } from '@asgardeo/auth-react' +import './App.css' -const App = () => { -const { state, signIn, signOut } = useAuthContext(); +function App() { + const { state, signIn, signOut } = useAuthContext(); -return ( + return ( <> - { - state.isAuthenticated - ? - : - } + {state.isAuthenticated ? ( + + ) : ( + + )} -) -}; + ) +} -export default App; +export default App ``` Visit your app's homepage at [http://localhost:5173](http://localhost:5173). @@ -173,27 +173,28 @@ Visit your app's homepage at [http://localhost:5173](http://localhost:5173). ## Display logged in user details -Modified the code as below to see logged in user details. +Modify the code as below to see logged in user details. -```javascript -... +```javascript hl_lines="11" +import { useAuthContext } from '@asgardeo/auth-react' +import './App.css' -const App = () => { -... +function App() { + const { state, signIn, signOut } = useAuthContext(); -return ( + return ( <> - { - state.isAuthenticated ? - <> -

Welcome {state.username}

- - - : - } + {state.isAuthenticated ? ( + <> +

Welcome {state.username}

+ + + ) : ( + + )} -) -}; + ) +} -... +export default App ``` diff --git a/en/asgardeo/hooks.py b/en/asgardeo/hooks.py index 6cc462c786..17b045c0c1 100644 --- a/en/asgardeo/hooks.py +++ b/en/asgardeo/hooks.py @@ -19,10 +19,11 @@ def parse_json(file_path): files_to_remove = parse_json(os.path.join(os.getcwd(), 'features.json')) def on_files(files, config): - for file in list(files): - if file.src_uri in files_to_remove['page']: - files.remove(file) - return files + if os.getenv("ENABLE_HOOKS") == "true": + for file in list(files): + if file.src_uri in files_to_remove['page']: + files.remove(file) + return files def remove_nav_item(nav_items): filtered_items = [] @@ -45,9 +46,9 @@ def remove_nav_item(nav_items): return filtered_items def on_config(config): + if os.getenv("ENABLE_HOOKS") == "true": + for feature, enabled in files_to_remove['feature'].items(): + config[feature] = enabled - for feature, enabled in files_to_remove['feature'].items(): - config[feature] = enabled - - config['nav'] = remove_nav_item(config['nav']) - return config + config['nav'] = remove_nav_item(config['nav']) + return config diff --git a/en/asgardeo/mkdocs.yml b/en/asgardeo/mkdocs.yml index 845eda7e4a..08787ad888 100644 --- a/en/asgardeo/mkdocs.yml +++ b/en/asgardeo/mkdocs.yml @@ -409,6 +409,7 @@ nav: - Organization management API: apis/organization-management.md - Password expiring users identification API: apis/password-expiring-users-identification.md - Role management (SCIM 2.0) API: apis/roles.md + - Rule Metadata API: apis/rule-metadata-rest-api.md - User management: - SCIM 2.0 API: - SCIM 2.0 API: apis/scim2/index.md @@ -514,7 +515,18 @@ nav: - Securing Routes: complete-guides/nodejs/securing-routes-within-the-app.md - Accessing protected API : complete-guides/nodejs/accessing-protected-api.md - Next Steps: complete-guides/nodejs/next-steps.md - + - Angular Guide: + - Introduction: complete-guides/angular/introduction.md + - Prerequisite: complete-guides/angular/prerequisite.md + - Register an application: complete-guides/angular/register-an-application.md + - Create a Angular app: complete-guides/angular/create-app.md + - Configure Asgardeo provider: complete-guides/angular/install-asgardeo-sdk.md + - Add login and logout: complete-guides/angular/add-login-and-logout.md + - Display user details: complete-guides/angular/display-logged-in-user-details.md + - Securing Routes: complete-guides/angular/securing-routes-within-the-app.md + - Accessing protected API : complete-guides/angular/accessing-protected-api.md + - Manage tokens in Angular : complete-guides/angular/manage-tokens.md + - Next Steps: complete-guides/angular/next-steps.md not_in_nav: | /page-not-found.md /get-started/explore-asgardeo.md diff --git a/en/identity-server/6.1.0/docs/apis/restapis/application.yaml b/en/identity-server/6.1.0/docs/apis/restapis/application.yaml index ab0008eb7f..d862b00ca5 100644 --- a/en/identity-server/6.1.0/docs/apis/restapis/application.yaml +++ b/en/identity-server/6.1.0/docs/apis/restapis/application.yaml @@ -79,7 +79,10 @@ paths: operationId: createApplication description: > This API provides the capability to store the application information that is provided by users.
- Scope(Permission) required: `internal_application_mgt_create` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/create
+ Scope required:
+ * internal_application_mgt_create parameters: - in: query name: template @@ -136,12 +139,15 @@ paths: tags: - Applications summary: | - Create application from an exported XML, YAML, or JSON file. + Create application from an exported XML file. operationId: importApplication description: > This API provides the capability to create an application based on the - information provided in an XML, YAML, or JSON file.
- Scope(Permission) required: `internal_application_mgt_create` + information provided as a file.
+ Permission required:
+ * /permission/admin/manage/identity/applicationmgt/create
+ Scope required:
+ * internal_application_mgt_create requestBody: content: multipart/form-data: @@ -182,12 +188,15 @@ paths: tags: - Applications summary: | - Update application from an exported XML, YAML, or JSON file. + Update application from an exported XML file. operationId: importApplicationForUpdate description: > This API provides the capability to update an application based on the - information provided in an XML, YAML, or JSON file.
- Scope(Permission) required: `internal_application_mgt_update` + information that has been provided as an XML file.
+ Permission required:
+ * /permission/admin/manage/identity/applicationmgt/update
+ Scope required:
+ * internal_application_mgt_update requestBody: content: multipart/form-data: @@ -239,7 +248,10 @@ paths: operationId: getApplication description: > This API provides the capability to retrieve the application information by ID.
- Scope(Permission) required: `internal_application_mgt_view` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/view
+ Scope required:
+ * internal_application_mgt_view parameters: - name: applicationId in: path @@ -293,7 +305,10 @@ paths: operationId: patchApplication description: | This API provides the capability to partially update an application by ID.
- Scope(Permission) required: `internal_application_mgt_update` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/update
+ Scope required:
+ * internal_application_mgt_update parameters: - name: applicationId in: path @@ -341,7 +356,10 @@ paths: operationId: deleteApplication description: | This API provides the capability to delete an application by ID.
- Scope(Permission) required: `internal_application_mgt_delete` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/delete
+ Scope required:
+ * internal_application_mgt_delete parameters: - name: applicationId in: path @@ -383,7 +401,10 @@ paths: Export application as an XML file. description: | This API provides the capability to retrieve the application as an XML file.
- Scope(Permission) required: `internal_application_mgt_view` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/view
+ Scope required:
+ * internal_application_mgt_view parameters: - name: applicationId in: path @@ -430,7 +451,10 @@ paths: Change application owner. description: | This API provides the capability to change the application owner.
- Scope(Permission) required: `internal_organization_admin` + Permission required:
+ * /permission/admin
+ Scope required:
+ * SYSTEM parameters: - name: applicationId in: path @@ -477,7 +501,10 @@ paths: operationId: getConfiguredAuthenticators description: | This API provides the capability to retrieve the configured authenticators.
- Scope(Permission) required: `internal_application_mgt_view` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/view
+ Scope required:
+ * internal_application_mgt_view parameters: - name: applicationId in: path @@ -525,7 +552,10 @@ paths: operationId: getResidentApplication description: | This API provides the capability to retrieve the resident application information.
- Scope(Permission) required: `internal_application_mgt_view` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/view
+ Scope required:
+ * internal_application_mgt_view responses: '200': description: OK @@ -563,7 +593,10 @@ paths: operationId: updateResidentApplication description: > This API provides the capability to update the resident application configuration.
- Scope(Permission) required: `internal_application_mgt_update` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/update
+ Scope required:
+ * internal_application_mgt_update responses: '200': description: Successful @@ -622,7 +655,10 @@ paths: operationId: getInboundAuthenticationConfigurations description: > This API provides the capability to retrieve authentication protocol configurations of an application.
- Scope(Permission) required: `internal_application_mgt_view` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/view
+ Scope required:
+ * internal_application_mgt_view parameters: - name: applicationId in: path @@ -668,7 +704,10 @@ paths: operationId: getInboundSAMLConfiguration description: > This API provides the capability to retrieve SAML2 authentication protocol parameters of an application.
- Scope(Permission) required: `internal_application_mgt_view` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/view
+ Scope required:
+ * internal_application_mgt_view parameters: - name: applicationId in: path @@ -713,7 +752,10 @@ paths: operationId: updateInboundSAMLConfiguration description: > This API provides the capability to store SAML2 authentication protocol parameters of an application.
- Scope(Permission) required: `internal_application_mgt_update` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/update
+ Scope required:
+ * internal_application_mgt_update - There are three methods to create/update SAML2 authentication protocol configuration. 1. Metadata File (by sending the Base64 encoded content of the metadata file.) @@ -779,7 +821,10 @@ paths: operationId: deleteInboundSAMLConfiguration description: > This API provides the capability to delete SAML2 authentication protocol parameters of an application.
- Scope(Permission) required: `internal_application_mgt_delete` + Permissi on required:
+ * /permission/admin/manage/identity/applicationmgt/delete
+ Scope required:
+ * internal_application_mgt_delete parameters: - name: applicationId in: path @@ -820,7 +865,10 @@ paths: Retrieve OIDC authentication protocol parameters. description: > This API provides the capability to retrieve OIDC authentication protocol parameters of an application.
- Scope(Permission) required: `internal_application_mgt_view` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/view
+ Scope required:
+ * internal_application_mgt_view operationId: getInboundOAuthConfiguration parameters: - name: applicationId @@ -865,7 +913,10 @@ paths: Update OIDC authentication protocol parameters. description: > This API provides the capability to store OIDC authentication protocol parameters of an application.
- Scope(Permission) required: `internal_application_mgt_update` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/update
+ Scope required:
+ * internal_application_mgt_update operationId: updateInboundOAuthConfiguration parameters: - name: applicationId @@ -928,7 +979,10 @@ paths: Delete OIDC authentication protocol parameters. description: > This API provides the capability to delete OIDC authentication protocol parameters of an application.
- Scope(Permission) required: `internal_application_mgt_delete` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/delete
+ Scope required:
+ * internal_application_mgt_delete operationId: deleteInboundOAuthConfiguration parameters: - name: applicationId @@ -970,7 +1024,10 @@ paths: Regenerate the OAuth2/OIDC client secret. description: | This API regenerates the OAuth2/OIDC client secret.
- Scope(Permission) required: `internal_application_mgt_create` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/create
+ Scope required:
+ * internal_application_mgt_create operationId: regenerateOAuthClientSecret parameters: - name: applicationId @@ -1015,9 +1072,11 @@ paths: summary: | Revoke the OAuth2/OIDC client of application. description: | - This API revokes the OAuth2/OIDC client secret. - To re-activate the client, the client secret needs to be regenerated.
- Scope(Permission) required: `internal_application_mgt_create` + This API revokes the OAuth2/OIDC client secret. To re-activate the client, the client secret needs to be regenerated.
+ Permission required:
+ * /permission/admin/manage/identity/applicationmgt/create
+ Scope required:
+ * internal_application_mgt_create operationId: revokeOAuthClient parameters: - name: applicationId @@ -1060,7 +1119,10 @@ paths: description: > This API provides the capability to retrieve Passive STS authentication protocol parameters of an application.
- Scope(Permission) required: `internal_application_mgt_view` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/view
+ Scope required:
+ * internal_application_mgt_view operationId: getPassiveStsConfiguration parameters: - name: applicationId @@ -1105,7 +1167,10 @@ paths: Update Passive STS authentication protocol parameters. description: > This API provides the capability to store passive STS authentication protocol parameters of an application.
- Scope(Permission) required: `internal_application_mgt_update` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/update
+ Scope required:
+ * internal_application_mgt_update operationId: updatePassiveStsConfiguration parameters: - name: applicationId @@ -1171,7 +1236,10 @@ paths: description: > This API provides the capability to delete Passive STS authentication protocol parameters of an application.
- Scope(Permission) required: `internal_application_mgt_delete` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/delete
+ Scope required:
+ * internal_application_mgt_delete operationId: deletePassiveStsConfiguration parameters: - name: applicationId @@ -1214,7 +1282,10 @@ paths: description: > This API provides the capability to retrieve Passive STS authentication protocol parameters of an application.
- Scope(Permission) required: `internal_application_mgt_view` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/view
+ Scope required:
+ * internal_application_mgt_view operationId: getWSTrustConfiguration parameters: - name: applicationId @@ -1259,7 +1330,10 @@ paths: Update WS Trust authentication protocol parameters. description: > This API provides the capability to store WS Trust authentication protocol parameters of an application.
- Scope(Permission) required: `internal_application_mgt_update` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/update
+ Scope required:
+ * internal_application_mgt_update operationId: updateWSTrustConfiguration parameters: - name: applicationId @@ -1324,7 +1398,10 @@ paths: Delete WS Trust authentication protocol parameters. description: > This API provides the capability to delete WS Trust authentication protocol parameters of an application.
- Scope(Permission) required: `internal_application_mgt_delete` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/delete
+ Scope required:
+ * internal_application_mgt_delete operationId: deleteWSTrustConfiguration parameters: - name: applicationId @@ -1367,7 +1444,10 @@ paths: description: > This API provides the capability to retrieve custom inbound authentication protocol parameters of an application.
- Scope(Permission) required: `internal_application_mgt_view` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/view
+ Scope required:
+ * internal_application_mgt_view operationId: getCustomInboundConfiguration parameters: - name: applicationId @@ -1419,7 +1499,10 @@ paths: description: > This API provides the capability to store custom inbound authentication protocol parameters of an application.
- Scope(Permission) required: `internal_application_mgt_update` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/update
+ Scope required:
+ * internal_application_mgt_update operationId: updateCustomInboundConfiguration parameters: - name: applicationId @@ -1490,7 +1573,10 @@ paths: Delete custom inbound authentication protocol parameters. description: > This API provides the capability to delete custom inbound authentication protocol of an application.
- Scope(Permission) required: `internal_application_mgt_delete` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/delete
+ Scope required:
+ * internal_application_mgt_delete operationId: deleteCustomInboundConfiguration parameters: - name: applicationId @@ -1539,7 +1625,10 @@ paths: description: > This API provides the capability to retrieve the list of inbound authentication protocols available. If the query parameter 'customOnly' is set to true, only custom inbound protocols will be listed.
- Scope(Permission) required: `internal_application_mgt_view` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/view
+ Scope required:
+ * internal_application_mgt_view operationId: getInboundProtocols parameters: - $ref: '#/components/parameters/inboundProtocolsCustomOnly' @@ -1579,7 +1668,10 @@ paths: Retrieve all the metadata related to the auth protocol SAML. description: > This API provides the capability to retrieve all the metadata related to the auth protocol SAML.
- Scope(Permission) required: `internal_application_mgt_view` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/view
+ Scope required:
+ * internal_application_mgt_view operationId: getSAMLMetadata responses: '200': @@ -1621,7 +1713,10 @@ paths: description: > This API provides the capability to retrieve all the metadata related to the authentication protocol OAuth / OIDC.
- Scope(Permission) required: `internal_application_mgt_view` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/view
+ Scope required:
+ * internal_application_mgt_view operationId: getOIDCMetadata responses: '200': @@ -1654,7 +1749,10 @@ paths: Retrieve all the metadata related to the auth protocol WS Trust. description: > This API provides the capability to retrieve all the metadata related to the auth protocol WS_Trust.
- Scope(Permission) required: `internal_application_mgt_view` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/view
+ Scope required:
+ * internal_application_mgt_view operationId: getWSTrustMetadata responses: '200': @@ -1688,7 +1786,10 @@ paths: description: > This API provides the capability to retrieve all the metadata related to the custom auth protocol identified by the inboundProtocolId. The URL encoded inbound protocol name is used as inboundProtocolId.
- Scope(Permission) required: `internal_application_mgt_view` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/view
+ Scope required:
+ * internal_application_mgt_view operationId: getCustomProtocolMetadata parameters: - name: inboundProtocolId @@ -1728,7 +1829,10 @@ paths: Retrieve adaptive authentication sample templates. description: > This API provides the capability to retrieve the sample adaptive authentication templates.
- Scope(Permission) required: `internal_application_mgt_view` + Permission required:
+ * /permission/admin/manage/identity/applicationmgt/view
+ Scope required:
+ * internal_application_mgt_view operationId: getAdaptiveAuthTemplates responses: '200': @@ -1762,7 +1866,8 @@ paths: List application templates. description: | This API provides the capability to retrieve the list of templates available.
- Scope(Permission) required: `internal_application_mgt_view` + Scope required:
+ * internal_application_mgt_view parameters: - $ref: '#/components/parameters/limitWithoutDefaultQueryParam' - $ref: '#/components/parameters/offsetWithoutDefaultQueryParam' @@ -1810,7 +1915,8 @@ paths: operationId: createApplicationTemplate description: > This API provides the capability to store the application template provided by users.
- Scope(Permission) required: `internal_application_mgt_create` + Scope required:
+ * internal_application_mgt_create requestBody: content: application/json: @@ -1864,7 +1970,8 @@ paths: operationId: getApplicationTemplate description: > This API provides the capability to retrieve the application template from the template id.
- Scope(Permission) required: `internal_application_mgt_view` + Scope required:
+ * internal_application_mgt_view parameters: - $ref: '#/components/parameters/templateIdPathParam' responses: @@ -1913,7 +2020,8 @@ paths: operationId: updateApplicationTemplate description: | This API provides the capability to update an application template by the template ID.
- Scope(Permission) required: `internal_application_mgt_update` + Scope required:
+ * internal_application_mgt_update parameters: - $ref: '#/components/parameters/templateIdPathParam' requestBody: @@ -1962,7 +2070,8 @@ paths: operationId: deleteApplicationTemplate description: | This API provides the capability to delete an application template by template ID.
- Scope(Permission) required: `internal_application_mgt_delete` + Scope required:
+ * internal_application_mgt_delete parameters: - $ref: '#/components/parameters/templateIdPathParam' responses: @@ -2073,10 +2182,9 @@ components: required: false description: | Specifies the required parameters in the response. - Only 'advancedConfigurations', 'templateId', 'clientId', 'issuer', and 'associatedRoles.allowedAudience' - attributes are currently supported. + Currently supports for only 'advancedConfigurations', 'templateId', 'clientId', and 'issuer' attributes. - /applications?attributes=advancedConfigurations,templateId,clientId,issuer,associatedRoles.allowedAudience + /applications?attributes=advancedConfigurations,templateId,clientId schema: type: string exportSecretsQueryParam: @@ -2480,7 +2588,7 @@ components: example: "SAML2 Inbound" self: type: string - example: "/api/server/v1/applications/29048810-1447-4ea0-a348-30d15ab65fa3/inbound-protocols/saml" + example: "/t/carbon.super/api/server/v1/applications/29048810-1447-4ea0-a348-30d15ab65fa3/inbound-protocols/saml" ClaimConfiguration: type: object properties: diff --git a/en/identity-server/7.0.0/docs/quick-starts/react.md b/en/identity-server/7.0.0/docs/quick-starts/react.md index 0bdc5cdf45..e334853495 100644 --- a/en/identity-server/7.0.0/docs/quick-starts/react.md +++ b/en/identity-server/7.0.0/docs/quick-starts/react.md @@ -4,13 +4,14 @@ heading: React Quickstart description: Welcome to the React Quickstart guide! In this document, you will learn to build a React app, add user login and display user profile information using WSO2 Identity Server. what_you_will_learn: - Create new React app using Vite - - Install @asgardeo/auth-react package + - Install @asgardeo/auth-react package - Add user login and logout - Display user profile information prerequisites: - About 15 minutes - Set-up WSO2 Identity Server - - Install a JS package manager + - Install Node.js on your system. + - Make sure you have a JavaScript package manager like npm, yarn, or pnpm. - A favorite text editor or IDE source_code: React Vite App Sample whats_next: @@ -44,7 +45,7 @@ Create (a.k.a scaffold) your new React app using Vite. === "npm" - ``` bash + ```bash npm create vite@latest is-react -- --template react cd is-react @@ -56,26 +57,26 @@ Create (a.k.a scaffold) your new React app using Vite. === "yarn" - ``` bash + ```bash yarn create vite@latest is-react -- --template react cd is-react - yran install + yarn install yarn dev ``` === "pnpm" - ``` bash + ```bash pnpm create vite@latest is-react -- --template react cd is-react pnpm install - pnpm run dev + pnpm dev ``` ## Install @asgardeo/auth-react @@ -84,19 +85,19 @@ Asgardeo React SDK provides all the components and hooks you need to integrate A === "npm" - ``` bash + ```bash npm install @asgardeo/auth-react ``` === "yarn" - ``` bash + ```bash yarn add @asgardeo/auth-react ``` === "pnpm" - ``` bash + ```bash pnpm add @asgardeo/auth-react ``` @@ -120,29 +121,28 @@ Add the following changes to the `main.jsx` file. - `` -```javascript -import React from 'react'; -import ReactDOM from 'react-dom/client'; -import App from './App.jsx'; -import { AuthProvider } from '@asgardeo/auth-react'; -import './index.css'; - -const config = { - signInRedirectURL: "http://localhost:5173", - signOutRedirectURL: "http://localhost:5173", - clientID: "", - baseUrl: "https://localhost:9443", - scope: [ "openid","profile" ] -} - -ReactDOM.createRoot(document.getElementById('root')).render( - - - - - , -); - +```javascript hl_lines="5 9-17 19" +import { StrictMode } from 'react' +import { createRoot } from 'react-dom/client' +import './index.css' +import App from './App.jsx' +import { AuthProvider } from '@asgardeo/auth-react' + +createRoot(document.getElementById('root')).render( + + ', + baseUrl: 'https://localhost:9443', + scope: ['openid', 'profile'], + } } + > + + + +) ``` ## Add login and logout link to your app @@ -151,25 +151,25 @@ Asgardeo React SDK provides `useAuthContext` hook to conveniently access user au Replace the existing content of the `App.jsx` file with following content. -```javascript -import { useAuthContext } from "@asgardeo/auth-react"; -import './App.css'; +```javascript hl_lines="1 5 9-13" +import { useAuthContext } from '@asgardeo/auth-react' +import './App.css' -const App = () => { -const { state, signIn, signOut } = useAuthContext(); +function App() { + const { state, signIn, signOut } = useAuthContext(); -return ( + return ( <> - { - state.isAuthenticated - ? - : - } + {state.isAuthenticated ? ( + + ) : ( + + )} -) -}; + ) +} -export default App; +export default App ``` Visit your app's homepage at [http://localhost:5173](http://localhost:5173). @@ -180,27 +180,28 @@ Visit your app's homepage at [http://localhost:5173](http://localhost:5173). ## Display logged in user details -Modified the code as below to see logged in user details. +Modify the code as below to see logged in user details. -```javascript -... +```javascript hl_lines="11" +import { useAuthContext } from '@asgardeo/auth-react' +import './App.css' -const App = () => { -... +function App() { + const { state, signIn, signOut } = useAuthContext(); -return ( + return ( <> - { - state.isAuthenticated ? - <> -

Welcome {state.username}

- - - : - } + {state.isAuthenticated ? ( + <> +

Welcome {state.username}

+ + + ) : ( + + )} -) -}; + ) +} -... +export default App ``` diff --git a/en/identity-server/next/docs/apis/restapis/rule-metadata.yaml b/en/identity-server/next/docs/apis/restapis/rule-metadata.yaml new file mode 100644 index 0000000000..7f0413e922 --- /dev/null +++ b/en/identity-server/next/docs/apis/restapis/rule-metadata.yaml @@ -0,0 +1,378 @@ +openapi: 3.0.1 +info: + title: WSO2 Identity Server Rule Metadata REST API + description: "The Rule Metadata API provides the essential metadata required to configure rules dynamically based on the flow context. \nThe metadata retrieved by this API is designed to support rule configuration in the user interface (UI) by delivering information about each configurable field, the set of applicable comparison operators (e.g., equals, contains) for each field, and lists of possible values or options for fields.\n" + contact: + name: WSO2 + url: https://wso2.com/identity-and-access-management/ + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: v1 +servers: +- url: "https://{server-url}/t/{tenant-domain}/api/server/v1" + variables: + tenant-domain: + default: carbon.super + server-url: + default: localhost:9443 +security: +- OAuth2: [] +- BasicAuth: [] +paths: + /rules/metadata: + get: + tags: + - Metadata + summary: Get metadata for rule configuration. + description: |+ + This API provides a list of fields, associated metadata, and applicable operators for each field based on the specified flow type. This information is used to populate the UI for rule configuration. + + Scope (Permission) required: ``internal_rule_metadata_view`` + + operationId: getExpressionMeta + parameters: + - name: flow + in: query + description: | + Specifies the flow to retrieve rule metadata. This ensures that the metadata returned is relevant to the given flow. + + Note: At present, only the 'preIssueAccessToken' flow is supported. + required: true + style: form + explode: true + schema: + type: string + enum: + - preIssueAccessToken + - prePasswordUpdate + - preProfileUpdate + - preLogin + - postLogin + - inLogin + - preRegistration + - inRegistration + - inPasswordExpiry + responses: + "200": + description: Applicable fields and operators + content: + application/json: + schema: + $ref: '#/components/schemas/ExpressionMeta' + examples: + preIssueAccessToken: + summary: Sample response for pre-issue access token flow + value: + - field: + name: application + displayName: application + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: reference + valueReferenceAttribute: id + valueDisplayAttribute: name + links: + - href: /applications?offset=0&limit=10 + method: GET + rel: values + - href: /applications?filter=name+eq+*&limit=10 + method: GET + rel: filter + - field: + name: grantType + displayName: grant type + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: string + values: + - name: authorization_code + displayName: authorization code + - name: password + displayName: password + - name: refresh_token + displayName: refresh token + - name: client_credentials + displayName: client credentials + - name: urn:ietf:params:oauth:grant-type:token-exchange + displayName: token exchange + prePasswordUpdate: + summary: Sample response for pre-password update flow + value: + - field: + name: initiator + displayName: initiator + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: string + values: + - name: user + displayName: user + - name: admin + displayName: admin + - name: application + displayName: application + - field: + name: flow + displayName: flow + dependentFileds: + - initiator + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: string + values: + - name: reset + displayName: reset + - name: update + displayName: update + inLogin: + summary: Sample response for login flow + value: + - field: + name: role + displayName: user.role + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: reference + valueReferenceAttribute: id + valueDisplayAttribute: name + links: + - href: /scim2/Roles?offset=0&limit=10 + method: GET + rel: values + - href: /scim2/Roles?filter=name+eq+*&limit=10 + method: GET + rel: filter + - field: + name: group + displayName: user.group + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + value: + inputType: options + valueType: reference + valueReferenceAttribute: id + valueDisplayAttribute: name + links: + - href: /scim2/Groups?offset=0&limit=10 + method: GET + rel: values + - href: /scim2/Groups?filter=name+eq+*&limit=10 + method: GET + rel: filter + - field: + name: email + displayName: user.email + operators: + - name: equals + displayName: equals + - name: notEquals + displayName: not equals + - name: startsWith + displayName: starts with + - name: endsWith + displayName: ends with + - name: contains + displayName: contains + value: + inputType: input + valueType: string + "400": + description: Bad Request + "401": + description: Unauthorized + "500": + description: Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codeSamples: + - lang: Curl + source: | + curl --location 'https://localhost:9443/api/server/v1/rules/metadata?flow=preIssueAccessToken' \ + --header 'Authorization: Basic YWRtaW46YWRtaW4=' +components: + schemas: + ExpressionMeta: + type: array + description: Represents the metadata for rule expressions. It includes field definitions and associated operators. + items: + $ref: '#/components/schemas/FieldDefinition' + FieldDefinition: + type: object + properties: + field: + $ref: '#/components/schemas/Field' + operators: + type: array + description: | + Specifies the list of valid operators that can be applied to this field in rule expressions. Each operator defines a comparison or matching condition (e.g., \"equals\", \"contains\", \"greaterThan\") that determines how the field's value will be evaluated within a rule. + items: + $ref: '#/components/schemas/Operator' + value: + $ref: '#/components/schemas/Value' + Field: + type: object + properties: + name: + type: string + description: Name of the field. This is an immutable attribute and uniquely identifies the field allowed in the rule. + example: role + displayName: + type: string + description: Display name of the field. Use as a user friendly label of the field to show in UI. + example: user.role + dependantFields: + type: array + description: Lists the names of fields on which this field depends for its display or selection in the next expression. + example: [] + items: + type: string + Value: + type: object + properties: + inputType: + type: string + description: | + Defines how the field should be presented and populated in the rule configuration UI. This property indicates whether the field allows direct user input or if the values are selected from predefined options. Possible types include: + + - "input": Allows for direct user entry, such as text or numeric input. + - "options": Provides a list of selectable values, often fetched from an external data source, enabling users to pick from predefined choices. + enum: + - input + - options + valueType: + type: string + description: | + Specifies the expected data type for the field’s value within a rule expression. This property defines how the field's value should be interpreted when used in rule conditions. Possible types include: + - "string": Text value. + - "number": Numerical value. + - "boolean": True or false. + - "date": Date value. + - "reference": A reference to an external identifier, often used with options-type fields to indicate that the value is an ID or a unique attribute from related data." + enum: + - string + - number + - boolean + - date + - reference + valueReferenceAttribute: + type: string + description: "The key attribute in the options data (e.g., 'id') used to represent the option's selected value in rule expressions. Only available when 'valueType' is 'reference'." + example: id + valueDisplayAttribute: + type: string + description: "The attribute to show as the label for each option in the dropdown (e.g., 'name') when listing options. Only available when 'valueType' is 'reference'." + example: name + links: + type: array + description: Endpoints to retrieve or search for options dynamically. Included only when 'valueType' is 'reference'. + example: + - href: /scim2/roles?offset=0&limit=10 + method: GET + rel: values + - href: /scim2/roles/.search + method: GET + rel: filter + items: + $ref: '#/components/schemas/Link' + values: + type: array + description: "List of selectable values for options fields when 'valueType' is 'string', 'number', 'boolean', or 'date'." + items: + $ref: '#/components/schemas/ValueObject' + Operator: + type: object + properties: + name: + type: string + description: Name of the operator. The immutable identifier of the operator referenced within the rule expression. + displayName: + type: string + description: Display name of the operator. Use as a user friendly label of the operator to show in UI. + ValueObject: + type: object + properties: + name: + type: string + description: The name that uniquely identifies the option. + displayName: + type: string + description: The display name for the option. + Link: + type: object + properties: + href: + type: string + description: Url of the endpoint. + method: + type: string + description: Http method. + enum: + - GET + rel: + type: string + description: Indicates the endpoint’s relation to retrieving or filtering field values. + enum: + - values + - filter + Error: + type: object + properties: + code: + type: string + description: Error code + example: RMS-00000 + message: + type: string + description: Error message. + example: Some error message. + description: + type: string + description: Detailed error description. + example: Some error description. + traceId: + type: string + description: Trace identifier to refer at troubleshooting logs to troubleshoot the problem. + example: e0fbcfeb-3617-43c4-8dd0-7b7d38e13047 + securitySchemes: + BasicAuth: + type: http + scheme: basic + OAuth2: + type: oauth2 + flows: + authorizationCode: + authorizationUrl: https://localhost:9443/oauth2/authorize + tokenUrl: https://localhost:9443/oauth2/token + scopes: + read: internal_rule_metadata_view diff --git a/en/identity-server/next/docs/apis/rule-metadata-rest-api.md b/en/identity-server/next/docs/apis/rule-metadata-rest-api.md new file mode 100644 index 0000000000..922e18f65d --- /dev/null +++ b/en/identity-server/next/docs/apis/rule-metadata-rest-api.md @@ -0,0 +1,5 @@ +--- +template: templates/redoc.html +--- + + \ No newline at end of file diff --git a/en/identity-server/next/mkdocs.yml b/en/identity-server/next/mkdocs.yml index 2e3366785f..914554cd7d 100644 --- a/en/identity-server/next/mkdocs.yml +++ b/en/identity-server/next/mkdocs.yml @@ -784,6 +784,7 @@ nav: - Role management: - Roles v2 API: apis/roles-v2-rest-api.md - Roles v1 API (deprecated): apis/roles-v1-rest-api.md + - Rule Metadata API: apis/rule-metadata-rest-api.md - Server management: - Configuration management: - Configuration management API: apis/use-the-configuration-management-rest-apis.md