Quickstart: Configure single sign-on for applications using the Azure Spring Apps Enterprise plan

Article
10/12/2023

Note

Azure Spring Apps is the new name for the Azure Spring Cloud service. Although the service has a new name, you'll see the old name in some places for a while as we work to update assets such as screenshots, videos, and diagrams.

This article applies to: ❌ Basic/Standard ✔️ Enterprise

This quickstart shows you how to configure single sign-on for applications running on the Azure Spring Apps Enterprise plan.

Prerequisites

An Azure account with an active subscription. Create an account for free.
A license for the Azure Spring Apps Enterprise plan. For more information, see Enterprise plan in Azure Marketplace.
The Azure CLI version 2.45.0 or higher.
Git.
jq
The Azure Spring Apps Enterprise plan extension. Use the following command to remove previous versions and install the latest Enterprise plan extension. If you previously installed the spring-cloud extension, uninstall it to avoid configuration and version mismatches.
```
az extension add --upgrade --name spring
az extension remove --name spring-cloud
```
Complete the steps in Build and deploy apps to Azure Spring Apps using the Enterprise plan.

Prepare single sign-on credentials

To configure single sign-on for the application, you need to prepare credentials. The following sections describe steps for using an existing provider or provisioning an application registration with Microsoft Entra ID.

Use an existing provider

Follow these steps to configure single sign-on using an existing Identity Provider. If you're provisioning a Microsoft Entra App Registration, skip ahead to the following section, Create and configure an application registration with Microsoft Entra ID.

Configure your existing identity provider to allow redirects back to Spring Cloud Gateway for VMware Tanzu and API portal for VMware Tanzu. Spring Cloud Gateway has a single URI to allow re-entry to the gateway. API portal has two URIs for supporting the user interface and underlying API. The following commands retrieve these URIs that you add to your single sign-on provider's configuration.

export GATEWAY_URL=$(az spring gateway show \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-service-instance-name> | jq -r '.properties.url')

export PORTAL_URL=$(az spring api-portal show \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-service-instance-name> | jq -r '.properties.url')

echo "https://${GATEWAY_URL}/login/oauth2/code/sso"
echo "https://${PORTAL_URL}/oauth2-redirect.html"
echo "https://${PORTAL_URL}/login/oauth2/code/sso"

Obtain the Client ID and Client Secret for your identity provider.
Obtain the Issuer URI for your identity provider. You must configure the provider with an issuer URI, which is the URI that it asserts as its Issuer Identifier. For example, if the issuer-uri provided is https://example.com, then an OpenID Provider Configuration Request is made to https://example.com/.well-known/openid-configuration. The result is expected to be an OpenID Provider Configuration Response.

Note

You can only use authorization servers that support OpenID Connect Discovery protocol.
Obtain the JWK URI for your identity provider for use later. The JWK URI typically takes the form ${ISSUER_URI}/keys or ${ISSUER_URI}/<version>/keys. The Identity Service application uses the public JSON Web Keys (JWK) to verify JSON Web Tokens (JWT) issued by your single sign-on identity provider's authorization server.

Create and configure an application registration with Microsoft Entra ID

To register the application with Microsoft Entra ID, follow these steps. If you're using an existing provider's credentials, skip ahead to the following section, Deploy the Identity Service application.

Use the following command to create an application registration with Microsoft Entra ID and save the output:
```
az ad app create --display-name <app-registration-name> > ad.json
```

Use the following command to retrieve the application ID and collect the client secret:

export APPLICATION_ID=$(cat ad.json | jq -r '.appId')
az ad app credential reset --id ${APPLICATION_ID} --append > sso.json

Use the following command to assign a Service Principal to the application registration:
```
az ad sp create --id ${APPLICATION_ID}
```

Use the following commands to retrieve the URLs for Spring Cloud Gateway and API portal, and add the necessary Reply URLs to the Active Directory App Registration.

export APPLICATION_ID=$(cat ad.json | jq -r '.appId')

export GATEWAY_URL=$(az spring gateway show \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-service-instance-name> | jq -r '.properties.url')

export PORTAL_URL=$(az spring api-portal show \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-service-instance-name> | jq -r '.properties.url')

az ad app update \
    --id ${APPLICATION_ID} \
    --web-redirect-uris "https://${GATEWAY_URL}/login/oauth2/code/sso" "https://${PORTAL_URL}/oauth2-redirect.html" "https://${PORTAL_URL}/login/oauth2/code/sso"

Use the following command to retrieve the application's Client ID. Save the output to use later in this quickstart.
```
cat sso.json | jq -r '.appId'
```
Use the following command to retrieve the application's Client Secret. Save the output to use later in this quickstart.
```
cat sso.json | jq -r '.password'
```

Use the following command to retrieve the Issuer URI. Save the output to use later in this quickstart.

export TENANT_ID=$(cat sso.json | jq -r '.tenant')
echo "https://login.microsoftonline.com/${TENANT_ID}/v2.0"

Retrieve the JWK URI from the output of the following command. The Identity Service application uses the public JSON Web Keys (JWK) to verify JSON Web Tokens (JWT) issued by Active Directory.
```
export TENANT_ID=$(cat sso.json | jq -r '.tenant')
echo "https://login.microsoftonline.com/${TENANT_ID}/discovery/v2.0/keys"
```

Deploy the Identity Service application

To complete the single sign-on experience, use the following steps to deploy the Identity Service application. The Identity Service application provides a single route to aid in identifying the user.

Navigate to the project folder.

Use the following command to create the identity-service application:

az spring app create \
    --resource-group <resource-group-name> \
    --name identity-service \
    --service <Azure-Spring-Apps-service-instance-name>

Use the following command to enable externalized configuration for the identity service by binding to Application Configuration Service:

az spring application-configuration-service bind \
    --resource-group <resource-group-name> \
    --app identity-service \
    --service <Azure-Spring-Apps-service-instance-name>

Use the following command to enable service discovery and registration for the identity service by binding to Service Registry:

az spring service-registry bind \
    --resource-group <resource-group-name> \
    --app identity-service \
    --service <Azure-Spring-Apps-service-instance-name>

Use the following command to deploy the identity service:

az spring app deploy \
    --resource-group <resource-group-name> \
    --name identity-service \
    --service <Azure-Spring-Apps-service-instance-name> \
    --config-file-pattern identity/default \
    --source-path apps/acme-identity \
    --build-env BP_JVM_VERSION=17 \
    --env "JWK_URI=<jwk-uri>"

Use the following command to route requests to the identity service:

az spring gateway route-config create \
    --resource-group <resource-group-name> \
    --name identity-routes \
    --service <Azure-Spring-Apps-service-instance-name> \
    --app-name identity-service \
    --routes-file azure-spring-apps-enterprise/resources/json/routes/identity-service.json

Configure single sign-on for Spring Cloud Gateway

You can configure Spring Cloud Gateway to authenticate requests using single sign-on. To configure Spring Cloud Gateway to use single sign-on, follow these steps:

Use the following commands to configure Spring Cloud Gateway to use single sign-on:

export GATEWAY_URL=$(az spring gateway show \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-service-instance-name> | jq -r '.properties.url')

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-service-instance-name> \
    --api-description "Fitness Store API" \
    --api-title "Fitness Store" \
    --api-version "v1.0" \
    --server-url "https://${GATEWAY_URL}" \
    --allowed-origins "*" \
    --client-id <client-id> \
    --client-secret <client-secret> \
    --scope "openid,profile" \
    --issuer-uri <issuer-uri>

Instruct the cart service application to use Spring Cloud Gateway for authentication. Use the following command to provide the necessary environment variables:

az spring app update \
    --resource-group <resource-group-name> \
    --name cart-service \
    --service <Azure-Spring-Apps-service-instance-name> \
    --env "AUTH_URL=https://${GATEWAY_URL}" "CART_PORT=8080"

Instruct the order service application to use Spring Cloud Gateway for authentication. Use the following command to provide the necessary environment variables:

az spring app update \
    --resource-group <resource-group-name> \
    --name order-service \
    --service <Azure-Spring-Apps-service-instance-name> \
    --env "AcmeServiceSettings__AuthUrl=https://${GATEWAY_URL}"

Use the following command to retrieve the URL for Spring Cloud Gateway:
```
echo "https://${GATEWAY_URL}"
```
You can open the output URL in a browser to explore the updated application. The Log In function is now operational, allowing you to add items to the cart and place orders. After you sign in, the customer information button displays the signed-in username.

Configure single sign-on for API portal

You can configure API portal for VMware Tanzu to use single sign-on to require authentication before exploring APIs. Use the following commands to configure single sign-on for API portal:

export PORTAL_URL=$(az spring api-portal show \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-service-instance-name> | jq -r '.properties.url')

az spring api-portal update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-service-instance-name> \
    --client-id <client-id> \
    --client-secret <client-secret> \
    --scope "openid,profile,email" \
    --issuer-uri <issuer-uri>

Use the following commands to retrieve the URL for API portal:

export PORTAL_URL=$(az spring api-portal show \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-service-instance-name> | jq -r '.properties.url')

echo "https://${PORTAL_URL}"

You can open the output URL in a browser to explore the application APIs. You're directed to sign on before exploring APIs.

Clean up resources

If you plan to continue working with subsequent quickstarts and tutorials, you might want to leave these resources in place. When no longer needed, delete the resource group, which deletes the resources in the resource group. To delete the resource group by using Azure CLI, use the following commands:

echo "Enter the Resource Group name:" &&
read resourceGroupName &&
az group delete --name $resourceGroupName &&
echo "Press [ENTER] to continue ..."

Next steps

Continue on to any of the following optional quickstarts: