DOCSEARCHbyAlgolia
Submit Docs

WSO2 Identity Server Documentation

website·Indexed 29 days ago

https://wso2identityserver.pages.dev/

Documentation for WSO2 Identity Server, featuring guides on user onboarding, login security, and multi-factor authentication (TOTP, Email OTP, Passkeys, X509). Includes comprehensive API references for SCIM 2.0 (Users, Patch, Batch operations), Application Management REST API (v1), Identity Provider Management API (v1), Workflow Approval API (v1), and Keystore API (v1).

Tokens
31.4K
Snippets
119
Records
204
Agent score
73%

What's inside WSO2 Identity Server

  1. Overview of SCIM 1.1 API Endpoints

    The SCIM 1.1 API allows for the management of users and groups in WSO2 Identity Server. These endpoints are exposed over HTTPS and protected by Basic Auth (though OAuth is recommended for production).

    • SCIM User Endpoint: https://{IS_IP}:{IS_PORT}/wso2/scim/Users
    • Current User Endpoint: https://{IS_IP}:{IS_PORT}/wso2/scim/Users/me (Used for operations targeting the currently authenticated user).
    • SCIM Group Endpoint: https://{IS_IP}:{IS_PORT}/wso2/scim/Groups

  2. Overview of Multi-Factor Authentication (MFA) in WSO2 Identity Server

    Multi-Factor Authentication (MFA) in WSO2 Identity Server enhances security by requiring two or more independent credentials from different categories to grant access to resources. The three categories of factors are:

    • Knowledge factor: Something the user knows (e.g., password, PIN).
    • Possession factor: Something the user has (e.g., FIDO key, ATM card).
    • Inherence factor: Something the user is (e.g., fingerprint, iris pattern).

    By default, WSO2 Identity Server uses username and password authentication. Users can build an authentication chain in the WSO2 Identity Server Console to include multiple authenticators, potentially replacing the default username/password with social or enterprise logins.

  3. Overview of WSO2 Identity Server IAM capabilities

    WSO2 Identity Server is an Identity and Access Management (IAM) solution designed to simplify user authentication and authorization across an organization. Its core capabilities include:

    • Single Sign-On (SSO) & Federation: Unifies sign-ins to eliminate multiple credentials and supports identity federation.
    • Access Control: Manages application access based on user or group permission levels.
    • Strong & Adaptive Authentication: Supports Multi-Factor Authentication (MFA) including Email OTP, SMS OTP, and FIDO Passkeys. Adaptive authentication allows security levels to be defined based on device, location, and usage context.
    • User Lifecycle Management: Provides self-registration, profile management, and integration with heterogeneous userstores such as LDAP, Active Directory, and JDBC.
    • API Security & Authorization: Acts as an authorization server supporting OAuth, OpenID Connect, and SAML 2.0 standards, with support for high availability and failover.
    • Privacy & Compliance: Facilitates recording, reviewing, and revoking user consents to comply with privacy laws such as GDPR, CCPA, and LGDP.

  4. Overview of WSO2 Identity Server API Categories

    WSO2 Identity Server exposes its features via REST APIs, which are divided into four main categories based on their intended usage:

    • System APIs: Used for managing the WSO2 Identity Server system.
    • Management APIs: Consumed by applications where WSO2 Identity Server acts as the Identity Provider.
    • Organization APIs: Consumed by B2B SaaS applications for organization-level operations.
    • End User APIs: Used for operations on the currently authenticated user.

  5. Overview of WSO2 Identity Server SDKs and Sample Applications

    WSO2 Identity Server (WSO2 IS) provides a variety of SDKs and sample applications across different technologies to facilitate integration. Developers can use these to implement authentication and authorization flows using SAML and OIDC protocols.

  6. Understand SCIM2 Patch operation types and attribute categories

    WSO2 Identity Server supports SCIM Patch to update one or more attributes of a SCIM resource. To perform an update, you must identify the attribute type and the operation type.

    Attribute Types:

    • Singular attribute: Contains a single value (e.g., displayName).
    • Multi-valued attribute: Contains multiple values (e.g., emails).
    • Complex attribute: A singular or multi-valued attribute composed of simple attributes (e.g., addresses containing streetAddress, locality, etc.).
    • Simple attribute: A singular or multi-valued attribute with a primitive value; it cannot contain sub-attributes.

    Update Operations:

    • add: Adds a new value for the attribute.
    • replace: Replaces the existing value of an attribute.
    • remove: Deletes the existing value of an attribute.

  8. Understand WSO2 Identity Server 7.0.0 Console UI terminology changes

    The WSO2 Identity Server Console is now stable in version 7.0.0. Several management concepts from the old carbon management console have been renamed to align with the new UI:

    • Service Providers are now called Applications.
    • Identity Providers and Inbound/outbound authentication are now called Connections.

    The Console now provides templates for creating specific application types, including Single Page Applications (SPAs), server-side rendered web applications, mobile applications, and Machine-to-machine (M2M) applications.

  9. Application Management API Overview

    The Application Management REST API (v1) for WSO2 Identity Server allows developers to programmatically manage the following entities:

    • Applications: Create, update, delete, retrieve, and export applications (including XML-based imports/exports).
    • Authenticators: Manage configured authenticators.
    • Authorized APIs: Manage API authorizations and scopes for applications.
    • Inbound Protocols: Configure protocol-specific parameters for SAML2, OAuth/OIDC, Passive STS, WS Trust, and Custom protocols.
    • Application Templates: Manage reusable application templates.
    • Application Sharing: Share applications from a root organization to other organizations.

  10. Retrieve details for a specific approval task

    Get detailed information about a specific approval task using its unique task-id.

    Requirements:

    • Permission: /permission/admin/manage/humantask/viewtasks
    • Scope: internal_humantask_view
    • Authorization: OAuth2 or BasicAuth
    curl -X 'GET' \
'https://localhost:9443/api/users/v1/me/approval-tasks/451' \
-H 'accept: */*' \
-H 'Authorization: Basic YWRtaW46YWRtaW4='

  11. Configure the X.509 Certificate Authenticator

    Configure the X.509 authenticator in the deployment.toml file. This setup defines the endpoint used to extract the certificate from the browser and specifies which certificate attribute (e.g., CN or Email) serves as the user subject identifier.
    [authentication.authenticator.x509_certificate.parameters]
name = "x509CertificateAuthenticator"
enable = true
AuthenticationEndpoint = "https://localhost:8443/x509-certificate-servlet"
username = "CN"

# Optional: Store X509 certificate as a user claim
setClaimURI = "http://wso2.org/claims/userCertificate"
EnforceSelfRegistration = true

  12. Configure Gmail as the Email OTP provider

    To use Gmail as the email OTP provider, you must create a Google Cloud project, enable the Gmail API, and obtain OAuth2 credentials.

    1. Google Cloud Setup: Create a project in the Google Developer Console, enable the Gmail API, and create an OAuth client ID for a 'Web Application' with the redirect URI https://localhost:9443/commonauth.
    2. Obtain Tokens: Use a browser and a tool like SAML Tracer to visit the Google OAuth authorization URL (replacing <CLIENT_ID>) to get an authorization code. Then, exchange that code for an access and refresh token using a cURL request.
    3. Update IS Configuration: Add the Gmail credentials and tokens to the deployment.toml file.
    # Exchange authorization code for tokens
curl -v -X POST --basic -u <CLIENT-ID>:<CLIENT_SECRET> -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "grant_type=authorization_code&code=<AUTHORIZATION_CODE>&redirect_uri=https://localhost:9443/commonauth" https://www.googleapis.com/oauth2/v3/token
    [authentication.authenticator.email_otp]
name = "EmailOTP"
enable = true

[authentication.authenticator.email_otp.parameters]
GmailClientId = "<gmail_client_id>"
GmailClientSecret = "<gmail_client_secret>"
GmailRefreshToken = "<refresh_token>"
GmailEmailEndpoint = "https://www.googleapis.com/gmail/v1/users/<mail_address>/messages/send"
accessTokenRequiredAPIs = "Gmail"
GmailAuthTokenType = "Bearer"
GmailTokenEndpoint = "https://www.googleapis.com/oauth2/v3/token"