Configurar o NGINX Plus para SAML SSO com o Microsoft Entra ID

Para aumentar a segurança e melhorar a experiência do usuário, o F5 NGINX Plus (R29+) agora tem suporte para Security Assertion Markup Language (SAML). Um protocolo bem estabelecido que fornece logon único (SSO) para aplicativos da web, o SAML permite que um provedor de identidade (IdP) autentique usuários para acesso a um recurso e, em seguida, passe essas informações para um provedor de serviços (SP) para autorização.

Nesta postagem do blog, abordamos passo a passo como integrar o NGINX com o Microsoft Entra ID , anteriormente conhecido como Azure Active Directory (Azure AD), usando um aplicativo Web que não oferece suporte nativo ao SAML. Também abordamos como implementar o SSO para o aplicativo e integrá-lo ao ecossistema Microsoft Entra ID. Ao seguir o tutorial, você também aprenderá como o NGINX pode extrair declarações de uma asserção SAML (incluindo UPN, nome, sobrenome e associações de grupo) e, em seguida, passá-las para o aplicativo por meio de cabeçalhos HTTP.

O tutorial inclui três etapas:

1. Configurando o Microsoft Entra ID como um IdP
2. Configurando as configurações SAML e NGINX Plus como um proxy reverso
3. Testando a configuração

Para concluir este tutorial, você precisa:

• NGINX Plus (R$ 29+), que você pode obter como um teste gratuito de 30 dias
• Uma conta Microsoft Entra ID gratuita ou empresarial
• Um certificado SSL/TLS válido instalado no servidor NGINX Plus (este tutorial usa dev.sports.com.crt e dev.sports.com.key )
• Para verificar as asserções SAML, o que pode ser feito baixando o certificado público demonginx.cer do IdP

Observação : Este tutorial não se aplica a implantações do NGINX Open Source porque o armazenamento de chave-valor é exclusivo do NGINX Plus.

Usando o NGINX Plus como um provedor de serviços SAML

Nessa configuração, o NGINX Plus atua como um SP SAML e pode participar de uma implementação de SSO com um IdP SAML, que se comunica indiretamente com o NGINX Plus por meio do Agente do Usuário.

O diagrama abaixo ilustra o fluxo do processo SSO, com iniciação de SP e vinculações POST para solicitação e resposta. É importante observar novamente que esse canal de comunicação não é direto e é gerenciado pelo Agente do Usuário.

Figura 1: SSO iniciado por SAML SP com vinculações POST para AuthnRequest e Response

Passo 1: Configurar o Microsoft Entra ID como um provedor de identidade

Para acessar o portal de gerenciamento do Microsoft Entra ID, entre e navegue até o painel esquerdo. Selecione Microsoft Entra ID e clique no título do diretório que requer configuração de SSO. Depois de selecionado, escolha Aplicativos corporativos .

Figura 2: Escolha de aplicativos corporativos no portal de gerenciamento

Para criar um aplicativo, clique no botão Novo aplicativo na parte superior do portal. Neste exemplo, criamos um aplicativo chamado demonginx .

Figura 3: Criando um novo aplicativo no Microsoft Entra ID

Depois de ser redirecionado para a Visão geral do aplicativo recém-criado, vá para Introdução no menu à esquerda e clique em Logon único em Gerenciar . Em seguida, selecione SAML como o método de logon único .

Figura 4: Usando a seção SSO para iniciar a configuração SAML

Para configurar o SSO em seu aplicativo empresarial, você precisa registrar o NGINX Plus como um SP dentro do Microsoft Entra ID. Para fazer isso, clique no ícone de lápis ao lado de Edit em Basic SAML Configuration , como visto na Figura 5.

Adicione os seguintes valores e clique em Salvar :

• Identificador (ID da entidade) – https://dev.sports.com
• URL de resposta (URL do serviço de consumidor de declaração) – https://dev.sports.com/saml/acs
• URL de login : https://dev.sports.com
• URL de logout (opcional) : https://dev.sports.com/saml/sls

O uso de certificados de verificação é opcional. Ao habilitar esta configuração, duas opções de configuração no NGINX devem ser abordadas:

1. Para verificar a assinatura com uma chave pública, você precisa definir $saml_sp_sign_authn como true . Isso instrui o SP a assinar o AuthnRequest enviado ao IdP.
2. Forneça o caminho para a chave privada que será usada para esta assinatura configurando $saml_sp_signing_key . Certifique-se de carregar o certificado de chave pública correspondente no Microsoft Entra ID para verificação de assinatura.

Observação : Nesta demonstração, atributos e declarações foram modificados, e novos atributos SAML foram adicionados. Esses atributos SAML são enviados pelo IdP. Certifique-se de que sua configuração do NGINX esteja definida para receber e processar corretamente esses atributos. Você pode verificar e ajustar as configurações relacionadas no repositório NGINX GitHub .

Baixe o Certificado IdP (Raw) do Microsoft Entra ID e salve-o na sua instância do NGINX Plus.

Figura 5: Baixando o Certificado IdP (Raw) do Microsoft Entra ID

Figura 6: Adicionar um novo usuário ou grupo

No Microsoft Entra ID, você pode conceder acesso aos aplicativos da sua empresa habilitados para SSO adicionando ou atribuindo usuários e grupos.

No menu à esquerda, clique em Usuário e grupos e depois no botão superior Adicionar usuário/grupo .

Passo 2: Configurar as configurações SAML e NGINX Plus como um proxy reverso

Certifique-se de ter os certificados necessários antes de configurar arquivos no seu NGINX Plus SP:

• Certificados para encerrar sessão TLS ( dev.sports.com.crt e dev.sports.com.key )
• Certificado baixado do Microsoft Entra ID para verificação de assinatura do IdP ( demonginx.cer )

Observação : Os certificados precisam estar no formato SPKI.

Para iniciar esta etapa, baixe o certificado IdP do Microsoft Entra ID para verificação de assinatura. Em seguida, converta o formato PEM para DER:

Caso você queira verificar asserções SAML SP, é recomendável usar chaves públicas/privadas diferentes daquelas usadas para terminação TLS.

Extraia o certificado de chave pública no formato SPKI:

Edite o arquivo frontend.conf para atualizar estes itens:

• ssl_certificate – Atualizar para incluir o caminho do certificado TLS.
• ssl_certificate_key – Atualização para incluir o caminho da chave privada TLS.

Na implantação de produção, você pode usar diferentes destinos de backend com base nos requisitos do negócio. Neste exemplo, o backend fornece uma resposta personalizada:

Modificamos os atributos e declarações no Microsoft Entra ID adicionando novas declarações para o e-mail e objectid do usuário. Essas atualizações permitem que você forneça uma resposta mais personalizada e adaptada ao seu aplicativo, resultando em uma melhor experiência do usuário.

Figura 7: Atributos e declarações modificados no Microsoft Entra ID

O próximo passo é configurar o NGINX, que fará o proxy do tráfego para o aplicativo de backend. Nesta demonstração, o aplicativo SAML de backend está disponível publicamente em https://dev.sports.com .

Edite seu arquivo frontend.conf :

# This is file frontend.conf 
# This is the backend application we are protecting with SAML SSO 
upstream my_backend { 
    zone my_backend 64k; 
    server dev.sports.com; 
} 

# Custom log format to include the 'NameID' subject in the REMOTE_USER field 
log_format saml_sso '$remote_addr - $saml_name_id [$time_local] "$request" "$host" ' 
                    '$status $body_bytes_sent "$http_referer" ' 
                    '"$http_user_agent" "$http_x_forwarded_for"'; 

# The frontend server - reverse proxy with SAML SSO authentication 
# 
server { 
    # Functional locations implementing SAML SSO support 
    include conf.d/saml_sp.server_conf; 
 

    # Reduce severity level as required 
    error_log /var/log/nginx/error.log debug; 
    listen 443 ssl; 
    ssl_certificate     /home/ubuntu/dev.sports.com.crt; 
    ssl_certificate_key  /home/ubuntu/dev.sports.com.key; 
    ssl_session_cache shared:SSL:5m; 
 

    location / { 
        # When a user is not authenticated (i.e., the "saml_access_granted." 
        # variable is not set to "1"), an HTTP 401 Unauthorized error is 
        # returned, which is handled by the @do_samlsp_flow named location. 
        error_page 401 = @do_samlsp_flow; 

        if ($saml_access_granted != "1") { 
            return 401; 
        } 

        # Successfully authenticated users are proxied to the backend, 
        # with the NameID attribute passed as an HTTP header        
        proxy_set_header mail $saml_attrib_mail;  # Microsoft Entra ID's user.mail 
        proxy_set_header objectid $saml_attrib_objectid; # Microsoft Entra ID's objectid 
        access_log /var/log/nginx/access.log saml_sso; 
        proxy_pass http://my_backend; 
        proxy_set_header Host dev.sports.com; 
        return 200 "Welcome to Application page\n My objectid is $http_objectid\n My email is $http_mail\n"; 
        default_type text/plain; 

   } 
} 
# vim: syntax=nginx         

Para que os atributos saml_attrib_mail e saml_attrib_ objectid sejam refletidos nas configurações do NGINX, atualize a parte de armazenamento de chave-valor do saml_sp_configuration.conf da seguinte maneira:

keyval_zone    zone=saml_attrib_mail:1M                state=/var/lib/nginx/state/saml_attrib_email.json   timeout=1h; 
keyval   $cookie_auth_token $saml_attrib_mail    zone=saml_attrib_mail; 

 keyval_zone zone=saml_attrib_objectid:1M            state=/var/lib/nginx/state/saml_attrib_objectid.json   timeout=1h; 
keyval   $cookie_auth_token $saml_attrib_objectid   zone=saml_attrib_objectid; 

Em seguida, configure o arquivo de configuração do SAML SSO. Este arquivo contém as configurações primárias para o SP e o IdP. Para personalizá-lo de acordo com sua configuração específica de SP e IdP, você precisa ajustar os vários blocos map{} incluídos no arquivo.

Esta tabela fornece descrições das variáveis dentro de saml_sp_configuration.conf :

O código abaixo mostra os valores editados somente para este caso de uso em saml_sp_configuration.conf.

Observação : Certifique-se de que as partes restantes do arquivo de configuração ainda apareçam no arquivo (por exemplo, os armazenamentos de chave-valor). Certifique-se também de ajustar corretamente as variáveis no arquivo saml_sp_configuration.conf com base na sua implantação.

 # SAML SSO configuration 

map $host $saml_sp_entity_id { 
    # Unique identifier that identifies the SP to the IdP. 
    # Must be URL or URN. 
    default "https://dev.sports.com"; 
} 

map $host $saml_sp_acs_url { 
    # The ACS URL, an endpoint on the SP where the IdP  
    # will redirect to with its authentication response. 
    # Must match the ACS location defined in the "saml_sp.serer_conf" file. 
    default "https://dev.sports.com/saml/acs"; 
} 

map $host $saml_sp_request_binding { 
    # Refers to the method by which an authentication request is sent from 
    # the SP to an IdP during the Single Sign-On (SSO) process. 
    # Only HTTP-POST or HTTP-Redirect methods are allowed. 
    default 'HTTP-POST'; 
} 

map $host $saml_sp_sign_authn { 
    # Whether the SP should sign the AuthnRequest sent to the IdP. 
    default "false"; 
} 

map $host $saml_sp_decryption_key { 
    # Specifies the private key that the SP uses to decrypt encrypted assertion 
    # or NameID from the IdP. 
    default ""; 
} 

map $host $saml_sp_force_authn { 
    # Whether the SP should force re-authentication of the user by the IdP. 
    default "false"; 
} 

map $host $saml_sp_nameid_format { 
    # Indicates the desired format of the name identifier in the SAML assertion 
    # generated by the IdP. Check section 8.3 of the SAML 2.0 Core specification 
    # (http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf) 
    # for the list of allowed NameID Formats. 
    default "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"; 
} 

map $host $saml_sp_relay_state { 
    # Relative or absolute URL the SP should redirect to 
    # after successful sign on. 
    default ""; 
} 

map $host $saml_sp_want_signed_response { 
    # Whether the SP wants the SAML Response from the IdP 
    # to be digitally signed. 
    default "false"; 
} 

map $host $saml_sp_want_signed_assertion { 
    # Whether the SP wants the SAML Assertion from the IdP 
    # to be digitally signed. 
    default "true"; 
} 

map $host $saml_sp_want_encrypted_assertion { 
    # Whether the SP wants the SAML Assertion from the IdP 
    # to be encrypted. 
    default "false"; 
} 

map $host $saml_idp_entity_id { 
    # Unique identifier that identifies the IdP to the SP. 
    # Must be URL or URN. 
    default "https://sts.windows.net/8807dced-9637-4205-a520-423077750c60/"; 
} 

map $host $saml_idp_sso_url { 
    # IdP endpoint that the SP will send the SAML AuthnRequest to initiate 
    # an authentication process. 
    default "https://login.microsoftonline.com/8807dced-9637-4205-a520-423077750c60/saml2"; 
} 

map $host $saml_idp_verification_certificate { 
    # Certificate file that will be used to verify the digital signature 
    # on the SAML Response, LogoutRequest or LogoutResponse received from IdP. 
    # Must be public key in PKCS#1 format. See documentation on how to convert 
    # X.509 PEM to DER format. 
    default "/etc/nginx/conf.d/demonginx.spki"; 
} 

######### Single Logout (SLO) ######### 

map $host $saml_sp_slo_url { 
    # SP endpoint that the IdP will send the SAML LogoutRequest to initiate 
    # a logout process or LogoutResponse to confirm the logout. 
    default "https://dev.sports.com/saml/sls"; 
} 

map $host $saml_sp_slo_binding { 
    # Refers to the method by which a LogoutRequest or LogoutResponse 
    # is sent from the SP to an IdP during the Single Logout (SLO) process. 
    # Only HTTP-POST or HTTP-Redirect methods are allowed. 
    default 'HTTP-POST'; 
} 

map $host $saml_sp_sign_slo { 
    # Whether the SP must sign the LogoutRequest or LogoutResponse 
    # sent to the IdP. 
    default "false"; 
} 

map $host $saml_idp_slo_url { 
    # IdP endpoint that the SP will send the LogoutRequest to initiate 
    # a logout process or LogoutResponse to confirm the logout. 
    # If not set, the SAML Single Logout (SLO) feature is DISABLED and 
    # requests to the 'logout' location will result in the termination 
    # of the user session and a redirect to the logout landing page. 
    default "https://login.microsoftonline.com/8807dced-9637-4205-a520-423077750c60/saml2"; 
} 

map $host $saml_sp_want_signed_slo { 
    # Whether the SP wants the SAML LogoutRequest or LogoutResponse from the IdP 
    # to be digitally signed. 
    default "true"; 
} 

map $host $saml_logout_landing_page { 
    # Where to redirect user after requesting /logout location. This can be 
    # replaced with a custom logout page, or complete URL. 
    default "/_logout"; # Built-in, simple logout page 
} 

map $proto $saml_cookie_flags { 
    http  "Path=/; SameSite=lax;"; # For HTTP/plaintext testing 
    https "Path=/; SameSite=lax; HttpOnly; Secure;"; # Production recommendation 
} 

map $http_x_forwarded_port $redirect_base { 
    ""      $proto://$host:$server_port; 
    default $proto://$host:$http_x_forwarded_port; 
} 

map $http_x_forwarded_proto $proto { 
    ""      $scheme; 
    default $http_x_forwarded_proto; 
} 
# ADVANCED CONFIGURATION BELOW THIS LINE 
# Additional advanced configuration (server context) in saml_sp.server_conf 

######### Shared memory zones that keep the SAML-related key-value databases 

# Zone for storing AuthnRequest and LogoutRequest message identifiers (ID) 
# to prevent replay attacks. (REQUIRED) 
# Timeout determines how long the SP waits for a response from the IDP, 
# i.e. how long the user authentication process can take. 
keyval_zone zone=saml_request_id:1M                 state=/var/lib/nginx/state/saml_request_id.json                  timeout=5m; 

# Zone for storing SAML Response message identifiers (ID) to prevent replay attacks. (REQUIRED) 
# Timeout determines how long the SP keeps IDs to prevent reuse. 
keyval_zone zone=saml_response_id:1M                state=/var/lib/nginx/state/saml_response_id.json                 timeout=1h; 

# Zone for storing SAML session access information. (REQUIRED) 
# Timeout determines how long the SP keeps session access decision (the session lifetime). 
keyval_zone zone=saml_session_access:1M             state=/var/lib/nginx/state/saml_session_access.json              timeout=1h; 

# Zone for storing SAML NameID values. (REQUIRED) 
# Timeout determines how long the SP keeps NameID values. Must be equal to session lifetime. 
keyval_zone zone=saml_name_id:1M                    state=/var/lib/nginx/state/saml_name_id.json                     timeout=1h; 

# Zone for storing SAML NameID format values. (REQUIRED) 
# Timeout determines how long the SP keeps NameID format values. Must be equal to session lifetime. 
keyval_zone zone=saml_name_id_format:1M             state=/var/lib/nginx/state/saml_name_id_format.json              timeout=1h; 

# Zone for storing SAML SessionIndex values. (REQUIRED) 
# Timeout determines how long the SP keeps SessionIndex values. Must be equal to session lifetime. 
keyval_zone zone=saml_session_index:1M              state=/var/lib/nginx/state/saml_session_index.json               timeout=1h; 
  
# Zone for storing SAML AuthnContextClassRef values. (REQUIRED) 
# Timeout determines how long the SP keeps AuthnContextClassRef values. Must be equal to session lifetime. 
keyval_zone zone=saml_authn_context_class_ref:1M    state=/var/lib/nginx/state/saml_authn_context_class_ref.json     timeout=1h; 

# Zones for storing SAML attributes values. (OPTIONAL) 
# Timeout determines how long the SP keeps attributes values. Must be equal to session lifetime. 
keyval_zone zone=saml_attrib_uid:1M                 state=/var/lib/nginx/state/saml_attrib_uid.json                  timeout=1h; 
keyval_zone zone=saml_attrib_name:1M                state=/var/lib/nginx/state/saml_attrib_name.json                 timeout=1h; 
keyval_zone zone=saml_attrib_memberOf:1M            state=/var/lib/nginx/state/saml_attrib_memberOf.json             timeout=1h; 

######### SAML-related variables whose value is looked up by the key (session cookie) in the key-value database. 

# Required: 
keyval $saml_request_id     $saml_request_redeemed          zone=saml_request_id;               # SAML Request ID 
keyval $saml_response_id    $saml_response_redeemed         zone=saml_response_id;              # SAML Response ID 
keyval $cookie_auth_token   $saml_access_granted            zone=saml_session_access;           # SAML Access decision 
keyval $cookie_auth_token   $saml_name_id                   zone=saml_name_id;                  # SAML NameID 
keyval $cookie_auth_token   $saml_name_id_format            zone=saml_name_id_format;           # SAML NameIDFormat 
keyval $cookie_auth_token   $saml_session_index             zone=saml_session_index;            # SAML SessionIndex 
keyval $cookie_auth_token   $saml_authn_context_class_ref   zone=saml_authn_context_class_ref;  # SAML AuthnContextClassRef 

# Optional: 
keyval $cookie_auth_token   $saml_attrib_uid                zone=saml_attrib_uid; 
keyval $cookie_auth_token   $saml_attrib_name               zone=saml_attrib_name; 
keyval $cookie_auth_token   $saml_attrib_memberOf           zone=saml_attrib_memberOf; 
 

keyval_zone    zone=saml_attrib_mail:1M                state=/var/lib/nginx/state/saml_attrib_mail.json   timeout=1h; 
keyval         $cookie_auth_token $saml_attrib_mail    zone=saml_attrib_mail; 
  
keyval $cookie_auth_token   $saml_attrib_objectid           zone=saml_attrib_objectid; 
keyval_zone zone=saml_attrib_objectid:1M            state=/var/lib/nginx/state/saml_attrib_objectid.json             timeout=1h; 
  

######### Imports a module that implements SAML SSO and SLO functionality 
js_import samlsp from conf.d/saml_sp.js; 

Etapa 3: Testando a configuração

Duas partes são necessárias para testar a configuração:

1. Verificando o fluxo SAML
2. Testando a funcionalidade de logout iniciada pelo SP

Verificando o fluxo SAML

Depois de configurar o SAML SP usando o NGINX Plus e o IdP usando o Microsoft Entra ID, é crucial validar o fluxo SAML. Esse processo de validação garante que a autenticação do usuário por meio do IdP seja bem-sucedida e que o acesso aos recursos protegidos pelo SP seja concedido.

Para verificar o fluxo SAML iniciado pelo SP, abra seu navegador preferido e digite https://dev.sports.com na barra de endereço. Isso o direcionará para a página de login do IdP.

Figura 8: A página de login do IdP

Insira as credenciais de um usuário que está configurado na página de login do IdP. O IdP autenticará o usuário após o envio.

Figura 9: Inserindo as credenciais do usuário configurado

O usuário receberá acesso ao recurso protegido solicitado anteriormente após estabelecer uma sessão com sucesso. Posteriormente, esse recurso será exibido no navegador do usuário.

Figura 10: A página do aplicativo foi carregada com sucesso

Informações valiosas sobre o fluxo SAML podem ser obtidas verificando os logs do SP e do IdP. No lado do SP (NGINX Plus), certifique-se de que os cookies auth_token estejam definidos corretamente. No lado do IdP (ID do Microsoft Entra), certifique-se de que o processo de autenticação seja concluído sem erros e que a asserção SAML seja enviada ao SP.

O NGINX access.log deve ficar assim:

127.0.0.1 - - [14/Aug/2023:21:25:49 +0000] "GET / HTTP/1.0" 200 127 "https://login.microsoftonline.com/" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.1 Safari/605.1.15" "-" 

99.187.244.63 - Akash Ananthanarayanan [14/Aug/2023:21:25:49 +0000] "GET / HTTP/1.1" "dev.sports.com" 200 127 "https://login.microsoftonline.com/" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.1 Safari/605.1.15" "- 

Enquanto o NGINX debug.log se parece com isto:

2023/08/14 21:25:49 [info] 27513#27513: *399 js: SAML SP success, creating session _d4db9b93c415ee7b4e057a4bb195df6cd0be7e4d 

Testando a funcionalidade de logout iniciada pelo SP

O SAML Single Logout (SLO) permite que os usuários efetuem logout de todos os IdPs e SPs envolvidos com uma única ação. O NGINX Plus oferece suporte a cenários de logout iniciados por SP e IdP, melhorando a segurança e a experiência do usuário em ambientes SSO. Neste exemplo, usamos um cenário de logout iniciado pelo SP.

Figura 11: SLO iniciado por SAML SP com ligações POST/redirecionamento para LogoutRequest e LogoutResponse

Após autenticar sua sessão, efetue logout acessando a URL de logout configurada no seu SP. Por exemplo, se você configurou https://dev.sports.com/logout como URL de logout no NGINX Plus, insira essa URL na barra de endereços do seu navegador.

Figura 12: Saindo da sessão com sucesso

Para garantir um logout seguro, o SP deve iniciar uma solicitação SAML que é então verificada e processada pelo IdP. Esta ação efetivamente encerra a sessão do usuário, e o IdP enviará uma resposta SAML para redirecionar o navegador do usuário de volta ao SP.

Conclusão

Parabéns! O NGINX Plus agora pode servir como um SAML SP, fornecendo outra camada de segurança e conveniência ao processo de autenticação. Esse novo recurso é um avanço significativo para o NGINX Plus, tornando-o uma solução mais robusta e versátil para organizações que priorizam segurança e eficiência. 

Saiba mais sobre o uso do SAML com o NGINX Plus

Você pode começar a usar o SAML com o NGINX Plus hoje mesmo iniciando uma avaliação gratuita de 30 dias do NGINX Plus . Esperamos que você ache isso útil e agradecemos seu feedback.

Mais informações sobre o NGINX Plus com SAML estão disponíveis nos recursos abaixo.

• Anunciando o NGINX Plus R29
• Suporte SAML no NGINX Plus como uma implementação de referência no GitHub