Add Azure Document for SAML (#17416)

openmetadata-docs/content/v1.5.x-SNAPSHOT/deployment/security/saml/azure.md

@@ -0,0 +1,154 @@
+---
+title: SAML AWS SSO
+slug: /deployment/security/saml/azure
+---
+
+# SAML AZURE SSO
+
+Follow the sections in this guide to set up Azure SSO using SAML.
+
+{% note %}
+
+Security requirements for your **production** environment:
+- **DELETE** the admin default account shipped by OM.
+- **UPDATE** the Private / Public keys used for the [JWT Tokens](/deployment/security/enable-jwt-tokens) in case it is enabled.
+
+{% /note %}
+
+## Create OpenMetadata application
+
+### Step 1: Configure a new Application in Microsoft Entra ID
+
+- Login to [Azure Portal](https://portal.azure.com) as an administrator and search for Microsoft Entra ID.
+
+{% image src="/images/v1.5/deployment/security/saml/aws/saml-azure-1.png" alt="EnterpriseApplications" /%}
+
+- Click on `Enterprise Applications` and then ` + New Application ` .
+
+{% image src="/images/v1.5/deployment/security/saml/aws/saml-azure-2.png" alt="new-application" /%}
+
+- After that a new window will appear with different applications, click on `Create your own application`.
+
+{% image src="/images/v1.5/deployment/security/saml/aws/saml-azure-3.png" alt="create-own-application" /%}
+
+- Give your application a name and select `Integrate any other application you don't find in the gallery` and then click `Create`.
+
+{% image src="/images/v1.5/deployment/security/saml/aws/saml-azure-4.png" alt="name-application-create" /%}
+
+- Once you have the application created, open the app from list , and then click on `Single Sign-On` and then `SAML`.
+
+{% image src="/images/v1.5/deployment/security/saml/aws/saml-azure-5.png" alt="saml-create-single-sign-On" /%}
+
+- Edit `Basic SAML Configuration` and populate the values as shown below for `EntityId` and `Assertion Consumer Service Url`. These value should match the one configured with Openmetadata Server side for `samlConfiguration.sp.entityId` and `samlConfiguration.sp.acs` respectively. After this click `Save`.
+
+{% image src="/images/v1.5/deployment/security/saml/aws/saml-azure-6.png" alt="edit-basic-saml-configuration" /%}
+
+- Click on `Attributes and Claims` and click on the `Required Claim (NameId)`.
+
+{% image src="/images/v1.5/deployment/security/saml/aws/saml-azure-7.png" alt="edit-claims" /%}
+
+- You will see the values as below image, we need to set the value `Source Attribute` to a user mail value claim from the IDP. Click on `Edit` and then select the `Source Attribute` as `user.mail` or `user.userprincipalname` (in some cases this is also a mail) and then click `Save`.
+
+{% image src="/images/v1.5/deployment/security/saml/aws/saml-azure-8.png" alt="edit-claim-value" /%}
+
+- To Confirm the claim value we can navigate to user page and check the value of the user. In my case as you can see User Princpal Name is a my mail which i want to use for Openmetadata , so for me `user.userprincipalname` would be correct claim.
+
+{% image src="/images/v1.5/deployment/security/saml/aws/saml-azure-9.png" alt="user-claim-value" /%}
+
+{% note %}
+
+Security requirements for your **production** environment:
+- You must always communicate via signed Request for both request from SP to IDP and response from IDP to SP.
+- To do so we need to add SP certificate to IDP , so that IDP can validate the signed Auth Request coming from SP.
+
+- Generate the certificate using below command and then upload the certificate to IDP. 
+```shell
+openssl req -new -x509 -days 365 -nodes -sha256 -out saml.crt -keyout saml.pem
+openssl x509 -in saml.crt -out samlCER.cer -outform DER
+```
+
+- Under `Single Sign-On` you will see SAML Certificates, click on `Verification Certificates`.
+ 
+{% image src="/images/v1.5/deployment/security/saml/aws/saml-azure-`0.png" alt="verification-certificate" /%}
+
+- You can then check the `Require Verification Certificates` and import the certification with .cer format we generated previously.
+
+{% /note %}
+
+### Step 2: Setup `OpenMetadata Server` 
+
+- Open the downloaded metadata xml file, and populate the following properties in `openmetadata.yml`
+```yaml
+  samlConfiguration:
+    debugMode: ${SAML_DEBUG_MODE:-false}
+    idp:
+      entityId: ${SAML_IDP_ENTITY_ID:-"https://mocksaml.com/api/saml/sso"}
+      ssoLoginUrl: ${SAML_IDP_SSO_LOGIN_URL:-"https://saml.example.com/entityid"}
+      idpX509Certificate: ${SAML_IDP_CERTIFICATE:-""}
+      authorityUrl: ${SAML_AUTHORITY_URL:-"http://localhost:8585/api/v1/saml/login"}
+      nameId: ${SAML_IDP_NAME_ID:-"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"}
+    sp:
+      entityId: ${SAML_SP_ENTITY_ID:-"http://localhost:8585/api/v1/saml/metadata"}
+      acs: ${SAML_SP_ACS:-"http://localhost:8585/api/v1/saml/acs"}
+      spX509Certificate: ${SAML_SP_CERTIFICATE:-""}
+      callback: ${SAML_SP_CALLBACK:-"http://localhost:8585/saml/callback"}
+    security:
+      strictMode: ${SAML_STRICT_MODE:-false}
+      tokenValidity: ${SAML_SP_TOKEN_VALIDITY:-"3600"}
+      sendEncryptedNameId: ${SAML_SEND_ENCRYPTED_NAME_ID:-false}
+      sendSignedAuthRequest: ${SAML_SEND_SIGNED_AUTH_REQUEST:-false}
+      signSpMetadata: ${SAML_SIGNED_SP_METADATA:-false}
+      wantMessagesSigned: ${SAML_WANT_MESSAGE_SIGNED:-false}
+      wantAssertionsSigned: ${SAML_WANT_ASSERTION_SIGNED:-false}
+      wantAssertionEncrypted: ${SAML_WANT_ASSERTION_ENCRYPTED:-false}
+      wantNameIdEncrypted: ${SAML_WANT_NAME_ID_ENCRYPTED:-false}
+      keyStoreFilePath: ${SAML_KEYSTORE_FILE_PATH:-""}
+      keyStoreAlias: ${SAML_KEYSTORE_ALIAS:-""}
+      keyStorePassword: ${SAML_KEYSTORE_PASSWORD:-""}
+```
+
+- Populate the above config from xml metadata
+
+{% image src="/images/v1.5/deployment/security/saml/aws/saml-aws-8.png" alt="populate-metadata" /%}
+
+- IDP Config         
+    `entityID` -> Populate it from Metadata XML Entity ID
+    `HTTP-Redirect SSO Login URL` -> always select HTTP-Redirect Url for SSO Login Url
+    `X509 Certificate` -> This is also available in the IDP XML.
+    `NameIDFormat` -> from MetadataXML NameIDFormat
+    `authorityUrl` -> set as {http}/{https}://{domain}:{port}/api/v1/saml/login
+
+- SP Config
+  `entityId` -> -> set as {http}/{https}://{domain}:{port}/api/v1/saml/metadata
+  `acs` -> Assertion Consumer Url , set as {http}/{https}://{domain}:{port}/api/v1/saml/acs
+  `spX509Certificate` -> set to your X509 Signing Key
+  `callback` -> set as {http}/{https}://{domain}/api/v1/saml/callback
+
+{% note %}
+
+- Security Parameters can be configured in case we want to have signed or encrypted or both assertions.
+  In any case we decided to use above config for security then it is mandatory to provide keystore config,
+  from where the system can load the signing certificate or Private Key for encryption.  
+- For **production** environment , it is always suggested to keep these true
+```yaml
+      sendSignedAuthRequest: ${SAML_SEND_SIGNED_AUTH_REQUEST:-true}
+      wantMessagesSigned: ${SAML_WANT_MESSAGE_SIGNED:-true}
+      wantAssertionsSigned: ${SAML_WANT_ASSERTION_SIGNED:-true}
+```
+
+{% /note %}
+
+### Step 3: Setup JWT Configuration
+
+- Follow the guide here for JWT Configuration [Enable JWT Token](/deployment/security/enable-jwt-tokens).
+
+{% note %}
+
+Security requirements for your **production** environment:
+- **UPDATE** the Private / Public keys used for the [JWT Tokens](/deployment/security/enable-jwt-tokens) the ones shipped with OM are for POC only.
+
+{% /note %}
+
+### Step 4: Start the server
+
+- Set up for SAML is done, you should be routed to your IDP on trying to Sign-in.

openmetadata-docs/content/v1.5.x-SNAPSHOT/deployment/security/saml/index.md

@@ -82,4 +82,14 @@ More specific details on different IDPs can be found below:
   {% /inlineCallout %}
 {% /inlineCalloutContainer %}
 
+{% inlineCalloutContainer %}
+{% inlineCallout
+color="violet-70"
+icon="celebration"
+bold="Azure Saml"
+href="/deployment/security/saml/azure" %}
+Configure AWS as IDP.
+{% /inlineCallout %}
+{% /inlineCalloutContainer %}
+
 {% partial file="/v1.5/deployment/configure-ingestion.md" /%}