Prerequisites
OceanBase Migration Service (OMS) nodes support access through the HTTPS protocol.
The Microsoft Entra ID user is a cloud application administrator, application administrator, or owner of the service entity.
Create an enterprise application
Log in to the Microsoft Azure Entra ID page.
In the left-side navigation pane, click Manage > Enterprise applications.
On the All applications page, click + New application.
On the Browse Microsoft Entra Gallery page, click + Create your own application.
In the Create your own application dialog box, enter the name of the application and select Integrate any other application you don't find in the gallery (Non-gallery).
Click Create. Wait for the enterprise application to be created.
Add users and configure OMS access parameters
On the All applications page, click the name of the created enterprise application to go to the Overview page.
In the left-side navigation pane, click Manage > Users and groups, and add users to the enterprise application for logging in to OMS.
On the Users and groups page, click + Add user/group.
In the Users section of the Add assignment page, click the link to select users.
In the Users dialog box, select the users to be added and click Select.
The added users can log in to OMS by using Microsoft Entra ID.
- On the Add assignment page, click Assign.
Configure the OMS access parameters in the enterprise application.
On the Overview page of the enterprise application, click Manage > Single sign-on in the left-side navigation pane.
In the Select a single sign-on method section, click SAML.
On the Set up Single Sign-On with SAML page, click Edit on the right side of Basic SAML Configuration and configure the parameters.
In the Identifier (Entity ID) section, click Add identifier to add a custom identifier.
In the Reply URL (Assertion Consumer Service URL) section, click Add reply URL to add a custom URL.
The Reply URL points to the OMS management node that you want to access by using Microsoft Entra ID. It must be an address that can be accessed by one or more browsers. If you configure multiple URLs, each URL points to an OMS management node that will be accessed by Microsoft Entra ID. You can customize the relative path part of each URL. If you do not need to modify it, you can enter the default value
https://<your domain name or IP address>[:<port number>]/omsp/saml/SSO.Note
Each OMS management node only needs to be configured with one URL. If multiple nodes share a load balancer, you only need to configure the load balancer's URL.
In the Basic SAML Configuration dialog box, click Save in the upper-left corner.
Configure the access parameters of Microsoft Entra ID in the OMS console
For all OMS management nodes that need to access Microsoft Entra ID, you need to perform the following steps. If multiple management nodes share the same MetaDB, you only need to configure one node in Step 2, and the configuration can be shared.
Obtain the parameters from Microsoft Entra ID.
On the Overview page of the enterprise application, click Manage > Single sign-on in the left-side navigation pane.
In the Set up Single Sign-On with SAML > Basic SAML Configuration section, obtain Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL).
In the SAML Certificates section, obtain App Federation Metadata Url and Certificate (Base64).
Configure the SAML 2.0-related system parameters in the OMS console.
Log in to the OMS console by using an account with the root privileges.
In the left-side navigation pane, click System Management > System Parameters.
On the System Parameters page, search for the
authkeyword.
Click the edit icon in the Value column of the target parameter.
In the Modify Value dialog box, enter the corresponding values for each parameter.
OMS parameter Corresponding value oms.auth.saml2.sp-base-url The base URL for SAML 2.0 service providers, which is the root path for accessing the OMS node in a browser, including the port number (if any), but not ending with a slash (). For example, https://prxx.oms.xxxx:18089.oms.auth.saml2.certificate The Base64-encoded certificate content downloaded from Microsoft Entra ID, which starts with -----BEGIN CERTIFICATE-----and ends with-----END CERTIFICATE-----. This is the Certificate (Base64) obtained in the SAML Certificates section.oms.auth.saml2.entity-id The entity ID of the service provider (SP) OMS. Enter the entity ID obtained from Microsoft Entra ID. Notice
The value must be the same as the
Identifier (Entity ID)in Microsoft Entra ID.oms.auth.saml2.metadata-provider The metadata URL of Microsoft Entra ID. Enter the App Federation Metadata Url obtained in the SAML Certificates section. If your environment cannot access the Internet, you can upload the metadata file downloaded through the App Federation Metadata Url to each OMS management container in advance. Then, set the value of this parameter to file://<absolute path of the metadata file>. Example:- Directly use the URL, allowing OMS to automatically download it:
https://login.microsoftonline.com/xxx. - Use the downloaded local file:
file:///root/saml/idp-metadata.xml.
oms.auth.saml2.redirect-url The redirect URL after a successful authentication. Enter https://<domain name>:<port number>/oms-v2/. For example,https://pri1.oms.xxxx:18089/oms-v2/.oms.auth.sso-login-url The OMS single sign-on (SSO) URL. Enter https://<domain name>:<port number>/omsp/saml/login. For example,https://pri1.oms.xxxx:18089/omsp/saml/login.oms.auth.saml2.sso-path The callback URL after a successful login of the identity provider (IDP). This is the relative path for OMS SSO assertion consumption. Enter the relative path part of the custom reply URL specified in Microsoft Entra ID. If you have specified a default value for OMS in Microsoft Entra ID, you can leave this parameter at its default value.
For example, if you have specifiedhttps://xxx.xxx.xxx/login/saml2/ssoin the Reply URL of Microsoft Entra ID, enter/login/saml2/ssoin this parameter.(Optional) If you changed the default value of the system parameter
oms.auth.saml2.sso-pathin the previous step, you need to go to the OMS Docker management node and run the following command:sh /root/saml_config.sh consumer-url '<the oms.auth.saml2.sso-path parameter value>'Modify the system configuration to enable SAML login.
Notice
You must perform this step after you enter the corresponding values for each system parameter. Otherwise, SAML login will fail.
a. Log in to the container that corresponds to the IP address configured in the OMS system parameter oms.auth.sso-login-url.
```shell docker exec -it ${CONTAINER_NAME} bash ``` <main id="notice" type='notice'> <h4>Notice</h4> <p><code>CONTAINER_NAME</code> is the name of the created container. </p> </main>b. Edit the file
/home/ds/ghana/config/application-oms.properties.c. Change
oms.iam.auth=LOCALtooms.iam.auth=SAML2.d. Run the following command in the container to restart the management service.
```shell supervisorctl restart oms_console ```After the restart is successful, go to the OMS console login page, where you can see the Third-party Login option and log in to OMS using Microsoft Entra ID.
FAQ
OMS login page exception
Q: The log shows an error like Authentication statement is too old to be used with value xxxx-xx-xx, or you are redirected back to the OMS login page after clicking Log In.
A: If you are redirected back to the OMS login page after clicking Log In, and the /home/admin/logs/ghana/Ghana/common-default.log log contains this error, it indicates that Microsoft Entra ID login has exceeded 2 hours (OMS only supports users with login sessions within 2 hours for SSO). You can log in to your Microsoft account again and try SSO again.
Microsoft login page exception
Q: The Microsoft login page shows error code AADSTS50105.
A: This error indicates that the current login user does not have the permission to log in to OMS. To log in, you need to add the user to the corresponding enterprise application in OMS, as described in the Add users and configure OMS access parameters section.