Skip to Content

Aplicações

Registe aplicações para Single Sign-On através de OpenID Connect, SAML 2.0 ou WS-Federation, a partir do catálogo ou personalizadas, e controle o acesso.

Uma aplicação é tudo aquilo em que os seus utilizadores iniciam sessão através da plataforma: uma aplicação web, uma aplicação móvel, uma single-page application, um serviço que chama uma API ou uma aplicação empresarial legada. Registar uma aplicação estabelece a confiança entre ela e o Single Sign-On da plataforma e indica à plataforma como emitir tokens ou Assertions para ela.

As aplicações são geridas em Integrações → Aplicações na Admin Console.

A página Aplicações

A página Aplicações lista tudo o que registou, dividido em três separadores:

  • Aplicações: as aplicações em que as pessoas iniciam sessão, em duas secções. As Aplicações de integração são aplicações que adicionou a partir do catálogo integrado (apresentadas como Integração SSO), cada uma com as predefinições de protocolo do fornecedor. As Aplicações personalizadas são aplicações interativas que configurou por si próprio para OIDC, SAML ou WS-Federation.
  • Máquinas: serviços machine-to-machine que se autenticam com um client secret e em que nunca uma pessoa inicia sessão, bem como aplicações apenas de aprovisionamento.
  • Registos dinâmicos: tokens de acesso iniciais e as aplicações que se registaram a si próprias. Consulte Registo dinâmico de clientes.

Cada linha mostra a atividade de início de sessão da aplicação: um número de inícios de sessão e uma hora do último acesso, ou Nunca iniciou sessão (aplicações interativas) / Nunca utilizado (machine-to-machine) quando nunca foi chamada.

Utilize a caixa de pesquisa acima da lista para filtrar o separador atual por nome, tipo, client ID ou integração. Aparece uma faixa de limite perto do topo quando se aproxima do número de aplicações que o seu plano permite.

Dois botões iniciam uma nova aplicação: Explorar integrações (o catálogo) e Criar aplicação personalizada. Pesquise primeiro no catálogo: criar uma aplicação personalizada só faz sentido quando não existe nenhuma integração para o seu destino.

Protocolos

A plataforma emite identidade através de três protocolos. Escolhe um deles ao criar a aplicação:

  • OpenID Connect (OIDC): o padrão moderno para aplicações web, single-page, móveis e machine-to-machine. Suporta o fluxo authorization code com PKCE, refresh tokens, o device authorization grant, client credentials e back-channel logout.
  • SAML 2.0: o padrão consolidado de SSO empresarial. A plataforma atua como Identity Provider e emite Assertions assinadas (opcionalmente encriptadas), suportando inícios de sessão iniciados pelo IdP e pelo SP, bem como Single Logout.
  • WS-Federation: para Relying Parties mais antigas orientadas para a Microsoft (por exemplo, Exchange OWA). A plataforma emite tokens SAML 1.1 assinados através de um Security Token Service.

Que protocolo escolher

Escolha OIDC sempre que possível: para tudo o que desenvolve por si próprio e para qualquer aplicação de fornecedor que o suporte. Abrange todos os tipos de aplicação, desde aplicações de browser até machine-to-machine, e é nele que se encontram as capacidades de segurança mais recentes (PKCE, DPoP, os perfis Financial-grade API, token exchange). Escolha SAML 2.0 quando a aplicação não suportar mais nada, o que ainda é comum em software empresarial consolidado; a experiência de início de sessão para os utilizadores é a mesma. O WS-Federation existe para Relying Parties legadas; não o escolha para nada novo.

Tipos de aplicação

Quando cria uma aplicação personalizada, escolhe um tipo, que define predefinições de protocolo sensatas e decide que configuração é apresentada:

TipoProtocoloUtilize-o para
Web application (server-side)OIDCAplicações web do lado do servidor que conseguem manter um client secret confidencial.
Single-Page ApplicationOIDCAplicações de browser sem backend; autenticam-se com PKCE, sem client secret.
Aplicação nativaOIDCAplicações móveis e de ambiente de trabalho; autenticam-se com PKCE, sem client secret.
Device applicationOIDCDispositivos com entrada limitada que utilizam o fluxo device authorization.
Machine-to-MachineOIDCAcesso entre serviços com o grant client-credentials; sem início de sessão interativo.
SAML applicationSAML 2.0Um Service Provider SAML que confia na plataforma como o seu Identity Provider.
Aplicação WS-FederationWS-FederationUma Relying Party que consome tokens SAML 1.1.
Provisioning-only–Uma aplicação na qual apenas aprovisiona contas, sem Single Sign-On. Consulte Aprovisionamento de aplicações.

O facto de uma aplicação conseguir manter um secret confidencial (web, machine-to-machine) ou não (single-page, nativa, device) determina como se autentica no token endpoint e se é emitido um client secret. Quando escolhe um tipo, a plataforma normaliza os tipos de grant e de response permitidos em conformidade; não os define manualmente.

Escolher um tipo OIDC conforme a forma de implementação

Para uma aplicação OIDC personalizada, faça corresponder o tipo ao local onde o código é executado e à credencial que consegue proteger:

Forma de implementaçãoTipoCredencialFluxo recomendado
Aplicação web do lado do servidor (tem um backend que consegue guardar um secret)Web application (server-side)Client secret (confidencial)Authorization code
Single-page application (executada no browser)Single-Page ApplicationNenhuma (public client)Authorization code + PKCE
Aplicação móvel / de ambiente de trabalhoAplicação nativaNenhuma (public client)Authorization code + PKCE
Serviço de backend sem utilizador (servidor para servidor)Machine-to-MachineClient secret (confidencial)Client credentials; consulte APIs

Um public client (single-page, nativa, device) não consegue manter um secret em segurança, pelo que nunca recebe um client secret utilizável e depende do PKCE para proteger a troca do authorization code. Utilize um tipo confidencial apenas quando a sua aplicação conseguir guardar um secret do lado do servidor.

Uma aplicação de browser só pode chamar os endpoints de token e de userinfo a partir da origem (esquema, anfitrião e porta) de um dos seus redirect URIs; os pedidos de qualquer outra origem são recusados.

Adicionar uma aplicação

O catálogo contém integrações pré-configuradas para aplicações comuns. Cada uma inclui as predefinições de protocolo corretas, uma configuração guiada com os valores exatos a colar na aplicação de destino e, quando disponível, um modelo de aprovisionamento. Adicionar uma é um fluxo em duas etapas:

  1. Aceda a Integrações → Aplicações, escolha Explorar integrações e selecione a aplicação.
  2. Leia o ecrã de pré-requisitos e consentimento. Este lista o que a integração necessita (por exemplo, uma conta de administrador no sistema de destino) e que acessos irá utilizar. Confirme-o para continuar.
  3. Preencha o formulário de configuração breve e específico da integração (por exemplo, o domínio ou subdomínio da aplicação) e crie a aplicação.
  4. A aplicação é criada com as predefinições do catálogo já aplicadas; refine a sua configuração depois, nos separadores descritos abaixo.

Alguns comportamentos do catálogo que deve conhecer:

  • As integrações de instância única só podem ser configuradas uma vez: se já existir uma configurada, o catálogo bloqueia uma segunda. A maioria das integrações pode ser adicionada várias vezes (por exemplo, uma por ambiente).
  • As entradas do catálogo desativadas não podem ser adicionadas; aparecem para referência, mas o fluxo de criação rejeita-as.
  • Algumas entradas do catálogo são apenas de aprovisionamento: criam contas a jusante, mas não disponibilizam início de sessão. Consulte Aprovisionamento de aplicações.
  • Os mosaicos do catálogo têm uma etiqueta de maturidade. Uma integração bem estabelecida não mostra nenhuma; uma mais recente é marcada como beta (funcional, ainda em aperfeiçoamento) ou experimental (inicial, pode mudar). Prefira integrações estáveis para produção e teste uma integração beta ou experimental antes de depender dela.

Cada integração do catálogo inclui uma configuração guiada no fluxo de criação, com os valores exatos a colar na aplicação de destino (e, quando o aprovisionamento é suportado, os passos SCIM). Os passos específicos de cada aplicação encontram-se nessa configuração guiada e não nesta documentação, para que se mantenham sincronizados com a integração.

Nota de decisão: pesquise no catálogo antes de criar uma aplicação personalizada. Uma integração do catálogo poupa-lhe a configuração do protocolo e, quando disponível, o mapeamento de aprovisionamento. Crie uma aplicação personalizada apenas quando nenhuma integração corresponder ao seu destino.

The application list in the Admin Console

Como aplicação personalizada

  1. Na página Aplicações, escolha Criar aplicação.
  2. Introduza um nome e escolha o tipo (consulte a tabela acima).
  3. Guarde. A plataforma cria a aplicação com as predefinições de protocolo desse tipo. Para aplicações SAML e WS-Federation, gera também automaticamente um certificado de assinatura.
  4. Abra a aplicação e configure-a nos separadores abaixo.

Os clientes OpenID Connect também se podem registar a si próprios, autorizados por um token de acesso inicial que emite. Consulte Registo dinâmico de clientes.

Configurar uma aplicação

Cada aplicação abre com um conjunto de separadores. Os separadores e campos apresentados dependem do protocolo e do tipo.

Definições gerais

Disponíveis para todas as aplicações:

  • Nome e Descrição.
  • Contactos: as pessoas a quem perguntar sobre a aplicação, escolhidas entre os colaboradores. São meramente informativos: os contactos não recebem quaisquer direitos. As integrações do catálogo oferecem o mesmo campo no separador Definições.
  • Logótipo da aplicação e Application URI: utilizados para apresentar a aplicação no portal de aplicações do utilizador. Pode ser definido um segundo logótipo opcional para o modo escuro; este substitui o logótipo padrão enquanto o tema escuro estiver ativo e vale a pena defini-lo para logótipos que sejam eles próprios escuros. As aplicações criadas a partir do catálogo de integrações obtêm ambos os logótipos da entrada do catálogo.
  • Display in the app portal: se os utilizadores finais veem a aplicação como um mosaico que podem abrir. As integrações do catálogo oferecem o mesmo interruptor no separador Definições; uma nova integração começa visível (a menos que a respetiva entrada do catálogo indique o contrário) e a sua escolha é mantida em gravações posteriores. O mosaico só aparece quando a integração fornece um URL de aplicação, o que muitas integrações SAML não fazem; o separador Definições indica-lhe quando é esse o caso.

A secção Ações destrutivas, na parte inferior, contém: rodar o client secret, renovar o certificado de assinatura, alterar o tipo de aplicação e eliminar a aplicação. Cada ação pede-lhe que confirme escrevendo o nome da aplicação.

Definições de OpenID Connect

Para aplicações OIDC, configura:

  • Client ID: gerado automaticamente; só de leitura.

  • Client secret: emitido para aplicações confidenciais (web, machine-to-machine). Apresentado mascarado, com controlos para copiar e revelar. Consulte Rodar um client secret.

  • Token endpoint authentication method: como a aplicação se autentica no token endpoint: um client secret no corpo ou no cabeçalho do pedido, Private Key JWT (a aplicação assina uma assertion com a sua própria chave privada, pelo que não é trocado nenhum secret partilhado), ou nenhum para public clients. Em implementações dedicadas com uma periferia mutual TLS, são também oferecidos dois métodos baseados em certificados: Mutual TLS (certificado autoassinado), em que o certificado de cliente apresentado tem de corresponder a um registado em Chaves de cliente, e Mutual TLS (certificado assinado por uma CA), em que o certificado é verificado contra uma autoridade de certificação fornecida pelo cliente e correspondido pelo seu subject (preencha exatamente um dos campos subject DN ou DNS SAN). Noutras implementações, os dois métodos são apresentados, mas desativados. Consulte Financial-grade API security.

  • Grant types: os fluxos que a aplicação pode utilizar. As caixas de verificação apresentadas dependem do tipo:

    • Agir em nome de um utilizador: authorization code, refresh token (e implicit, quando ainda necessário; um access token de um fluxo implicit ou híbrido só é emitido com response_mode=form_post, nunca no fragmento do URL).
    • Agir em nome próprio: client credentials (machine-to-machine).
    • Token exchange: trocar um token por outro, utilizado quando um serviço precisa de chamar uma API a jusante como o utilizador original (delegação) e não em nome próprio.

    Os tipos de response são derivados dos grants que permite; não os define separadamente.

  • Redirect URIs e Post-logout redirect URIs: consulte URIs de redirecionamento e pós-logout.

  • Back-channel logout URI: um endpoint de servidor que a plataforma chama para terminar a sessão do utilizador nesta aplicação quando a sua sessão termina.

  • Initiate login URI: utilizado para inícios de sessão iniciados pelo IdP na aplicação.

  • Reforço do protocolo: interruptores que podem ser utilizados isoladamente ou fazer parte de um perfil de segurança, que os define e bloqueia:

    • Require proof of possession (DPoP): associa os access tokens emitidos à chave da aplicação, para que um token roubado não possa ser reutilizado.
    • Exigir tokens de acesso vinculados ao certificado (mTLS): associa os access tokens emitidos ao certificado de cliente TLS da aplicação. Oferecido em implementações dedicadas com uma periferia mutual TLS; não pode ser combinado com o requisito DPoP.
    • Exigir pushed authorization requests (PAR): a aplicação envia primeiro os seus parâmetros de autorização à plataforma por back-channel e redireciona o utilizador com uma referência curta, pelo que os parâmetros nunca aparecem no URL do browser. Oferecido apenas para aplicações que utilizam o authorization endpoint.
    • Exigir um request object assinado (JAR): os parâmetros de autorização só são aceites dentro de um JWT assinado pela aplicação. Tem de ser registada primeiro uma chave de cliente ou um JWKS URI; caso contrário, nenhum pedido de autorização pode ter êxito. Requer a subscrição Advanced ou Pro, tal como as chaves de cliente de que depende; sem ela, o interruptor é apresentado mas desativado, e uma definição efetuada anteriormente mantém-se em vigor.
  • Exigir consentimento do utilizador: pede ao utilizador que dê o seu consentimento antes de serem emitidos tokens.

  • Tempo de vida do token de ID e Idade máxima da autenticação: consulte Durações de tokens e logout.

  • OIDC discovery URL: o URL só de leitura .well-known/openid-configuration que a aplicação utiliza para encontrar os endpoints e as chaves de assinatura da plataforma. Entregue-o ao seu integrador.

As claims que a aplicação efetivamente recebe são configuradas no separador Atributos; consulte Atributos e claims.

URIs de redirecionamento e pós-logout

Uma incompatibilidade de redirect URI é a causa mais comum de SSO com falhas, pelo que deve configurá-los com cuidado.

  • Redirect URIs: os URLs de callback exatos para os quais a plataforma pode devolver o utilizador após o início de sessão. Obrigatórios para o fluxo authorization code. A correspondência é exata: uma barra final, uma porta diferente ou http em vez de https fazem com que a plataforma rejeite a resposta, e o utilizador vê um erro em vez de iniciar sessão. Se o URL que a sua aplicação envia não constar desta lista, o início de sessão falha.
  • Post-logout redirect URIs: os URLs de retorno para os quais a plataforma pode reencaminhar o utilizador após terminar a sessão.

Pode indicar várias entradas, uma por linha, para abranger vários ambientes. Evite wildcards e localhost em registos de produção: alargam os destinos para os quais um atacante pode redirecionar. Em vez disso, adicione uma aplicação de desenvolvimento separada com o seu próprio URI localhost.

Para SAML e WS-Federation, o equivalente é a lista de URLs ACS / URLs de resposta permitidos: quando o Request não indica um destino de retorno, a plataforma utiliza a primeira entrada (predefinida). No SAML, a porta predefinida é ignorada quando o URL ACS e o Issuer são comparados, pelo que https://host:443/... e https://host/... contam como a mesma entrada.

Resolução de problemas, o início de sessão devolve um erro em vez da aplicação: o URL de callback enviado pela sua aplicação não consta dos redirect URIs (ou difere numa barra, porta ou esquema). Copie o URL exato do erro ou da configuração da sua aplicação e adicione-o aqui.

Definições de SAML

Para aplicações SAML, configura a ligação ao Service Provider (SP). O separador está agrupado em cinco secções, pela ordem em que as percorre: Origem da configuração, Single Sign-On, Single Logout, Assinatura e encriptação e Dados do Identity Provider. O mapeamento de atributos encontra-se no seu próprio separador Atributos; consulte Atributos e claims.

Origem da configuração

Escolha um de três modos:

  • URL: cole o URL de metadados do SP e guarde. O URL é validado ao guardar: se não for possível alcançá-lo ou se não devolver metadados SAML válidos, a gravação é rejeitada, pelo que nunca é guardada uma origem com falhas. (Um botão Testar verifica o URL antes de guardar.) Opcionalmente, ative a atualização automática e escolha um intervalo (desde cada 5 minutos até diariamente) para voltar a obter os metadados de forma agendada, para que uma alteração de certificado ou de endpoint do lado do SP seja detetada sem nova importação; se uma atualização agendada falhar mais tarde, aparece um aviso em Problemas. A atualização automática só funciona com um URL https://. Aplica rotações de certificados, o endpoint de logout, os indicadores de assinatura e as alterações do assertion consumer service num anfitrião que o SP já utilizava, e regista cada alteração aplicada no registo de auditoria. Um novo entity ID ou um assertion consumer service num novo anfitrião não é aplicado automaticamente, uma vez que é para aí que vai cada resposta de início de sessão da aplicação: a aplicação mantém os seus metadados atuais e um problema pede-lhe que reveja a alteração. Utilize Obter agora para a aplicar, ou para atualizar de imediato em qualquer momento. Deixe a atualização automática desativada para importar os metadados uma vez e mantê-los fixos.
  • Ficheiro: largue o XML de metadados do SP.
  • Manual: preencha manualmente os campos nas secções abaixo.

Nos dois modos de metadados, os valores obtidos dos metadados são apresentados só de leitura na secção a que pertencem: o Entity ID e os endpoints ACS do SP em Single Sign-On, o seu endpoint de logout em Single Logout e os seus certificados, bem como os indicadores de assinatura declarados, em Assinatura e encriptação. Por isso, nunca é necessário ler o XML de metadados para saber o que está em vigor. Os campos de introdução correspondentes ficam ocultos enquanto uma importação estiver ativa, e os valores guardados permanecem intactos, pelo que voltar a Manual restaura o que foi introduzido manualmente da última vez.

Single Sign-On

  • URI do Assertion Consumer Service: para onde é enviada a Assertion SAML. Obrigatório. Quando o SP inicia um Request sem indicar um ACS, é utilizado o primeiro URL ACS (predefinido).
  • Método do Assertion Consumer Service: como a Assertion é entregue: POST, Redirect ou igual ao Request.
  • Audience: o identificador do SP. É utilizado como Audience quando um início de sessão começa sem um SAML Request, pelo que permanece editável também nos modos de metadados.
  • Início de sessão iniciado pelo IdP: permite que um início de sessão comece aqui em vez de no SP, por exemplo a partir do mosaico no portal de aplicações.

Single Logout

  • URI do serviço de Single Logout e o respetivo método: para onde são enviadas as mensagens de logout SAML destinadas a este SP. Quando definido, a aplicação participa no Single Logout: terminar a sessão na plataforma, ou noutra aplicação participante, termina também a sessão neste SP. Nos modos de metadados, ambos os valores são importados dos metadados do SP (é preferido POST quando o SP publica ambos os Bindings) e mantidos em sintonia a cada atualização dos metadados, pelo que só têm de ser introduzidos manualmente no modo manual. Quando os metadados não declaram nenhum endpoint de logout, a secção indica-o.
  • Entrega do logout: mostra se alguma vez foi bem-sucedido um logout de servidor para servidor para esta aplicação e quando foi a última vez.

A forma como o Request chega ao SP não requer configuração. Enquanto o utilizador termina a sessão num browser, o logout é entregue através dele (uma frame oculta por aplicação), o que permite a cada SP limpar os seus próprios cookies de sessão. Quando uma sessão termina sem browser (uma sessão terminada por um administrador, uma sessão inativa, uma sessão terminada como resposta de segurança, ou todas as sessões de uma conta que foi suspensa, eliminada ou cuja palavra-passe foi alterada ou reposta), ou quando o browser não conseguiu concluir a entrega, o Request é enviado diretamente de servidor para servidor. As aplicações acessíveis apenas a partir da rede do utilizador são, por isso, desligadas normalmente quando o utilizador está presente e não são comunicadas como falhas apenas porque a própria plataforma não as consegue alcançar. Uma aplicação cujo endpoint de logout respondia anteriormente e deixa de responder, ou que rejeita o Request, é assinalada em Problemas, onde uma entrada abrange a situação em vez de uma por cada fim de sessão.

Assinatura e encriptação

  • Requests recebidos: se o SP assina os seus Authn Requests e Logout Requests. Para tal, é necessário o seu certificado de assinatura, e os Requests não assinados ou mal assinados são então rejeitados. Enquanto o certificado estiver em falta, os Logout Requests do SP são recusados e um problema indica a aplicação.
  • Assinatura da Response: que parte da Response transporta a assinatura: a SAML Response, a Assertion ou ambas. É sempre aplicada pelo menos uma assinatura. Nos modos de metadados, a assinatura da Assertion segue os metadados do SP (WantAssertionsSigned); apenas a assinatura da Response provém desta definição.
  • Encriptação da Assertion: encripta a Assertion para este SP. Ative-a apenas quando o SP exigir Assertions encriptadas.
  • Certificado de assinatura do Service Provider: o certificado com base no qual os Requests recebidos são verificados.
  • Certificado de encriptação do Service Provider: só é necessário quando o SP publica um certificado separado para encriptação; caso contrário, é utilizado o seu certificado de assinatura.

Dados do Identity Provider

Tudo o que o SP necessita para confiar neste Identity Provider, só de leitura e com um botão de cópia: o Metadata URL (importá-lo abrange todos os outros valores), o Entity ID (Issuer), o URL de início de sessão, o URL de Single Logout e o certificado de assinatura com a respetiva impressão digital. Consulte Certificados de assinatura e encriptação.

Definições de WS-Federation

Para aplicações WS-Federation, o separador está agrupado em três secções (o mapeamento de atributos encontra-se no separador Atributos; consulte Atributos e claims):

  • Relying Party: o Realm ao qual o Request tem de corresponder e a lista de URLs de resposta permitidos como destinos de retorno (a primeira entrada é a predefinida).
  • Token de segurança: a duração do token, ou seja, durante quanto tempo o token SAML 1.1 emitido é válido.
  • Dados do Identity Provider: valores só de leitura para a Relying Party, cada um com um botão de cópia: o Federation Metadata URL, o Entity ID (Issuer) dos tokens emitidos, o URL de início de sessão para o qual a Relying Party envia os seus Requests e o certificado de assinatura com a respetiva impressão digital.

Atributos e claims

O separador Atributos responde a uma pergunta para todos os protocolos: o que fica esta aplicação a saber sobre o utilizador? O que oferece depende do protocolo, porque o SAML e o WS-Federation permitem nomear os atributos livremente, enquanto os nomes das claims OIDC são fixados pela especificação.

As aplicações machine-to-machine e device não têm este separador. Não recebem nem um ID token nem uma Assertion com atributos de utilizador.

SAML e WS-Federation

Ambos os protocolos emitem atributos de utilizador na Assertion e ambos permitem mudar o nome de cada um para o que a aplicação recetora espera.

  • Name ID source: selecione o campo do utilizador que se torna o subject da Assertion (o Name ID).
  • Emitted attributes: cada atributo padrão (básico) e cada atributo personalizado tem uma caixa de verificação e um campo de nome. A caixa de verificação decide se o atributo chega de todo à Assertion; o campo contém o nome exato com que é enviado. Edite o campo quando o SP esperar, por exemplo, mail em vez de email; o botão de reposição ao lado restaura o nome com que o atributo começou. Um atributo que não esteja assinalado não é enviado, e o seu nome não pode ser editado até o assinalar.

Este mapeamento altera apenas os nomes que o recetor vê; não transforma nem calcula valores de atributos. O NameFormat que a Assertion declara junto a um atributo segue o nome que introduzir: um nome em forma de URI é declarado como URI, um nome simples como basic.

O Filtro de grupos abaixo do mapeamento decide que grupos acabam na Assertion. A Assertion transporta distinguished names, e o filtro compara tanto com o distinguished name como com o nome simples do grupo, pelo que um termo como APP-JIRA funciona com qualquer um dos modos de correspondência.

OIDC

  • Claims padrão: uma vista geral só de leitura das claims disponibilizadas por scope, para que possa ver o que a aplicação obtém pelos scopes que pede. Estes nomes são fixados pela especificação OpenID Connect e não podem ser alterados. As claims marcadas com um asterisco exigem adicionalmente que o diretório do utilizador ative o campo de perfil subjacente: o scope por si só não as coloca no token. Uma claim marcada como obsoleta continua a ser emitida, mas será removida numa versão futura, pelo que não deve basear uma nova integração nela. Atualmente, é o caso da claim roles no scope groups: as funções pertencem ao access token, emitido através de uma API com RBAC ativado, ou ao scope roles.
  • Claims próprios: selecione os atributos personalizados que a aplicação recebe adicionalmente. Cada atributo selecionado é emitido como claim de nível superior com o seu próprio nome, ao lado das claims padrão, quando a aplicação pede o scope profile. Um valor só é emitido quando o atributo está atribuído ao diretório do utilizador, pelo que selecionar um atributo nunca revela mais do que aquilo que esse utilizador efetivamente tem. Por predefinição, nada está selecionado: uma aplicação só recebe um atributo personalizado depois de o ativar aqui.
  • Group-name format: como cada grupo é designado na claim groups: pelo seu distinguished name, pelo seu nome simples ou pelo seu id. Escolha a forma que a aplicação espera quando mapeia grupos para os seus próprios acessos.
  • Filtro de grupos: os grupos de que a aplicação é informada. Sem filtro, é enviado cada grupo a que o utilizador pertence, e um utilizador sincronizado a partir de um diretório tem facilmente algumas centenas, o que sobrecarrega o token e entrega a cada aplicação toda a estrutura interna de grupos. Introduza um termo e escolha se um grupo tem de o conter ou começar por ele. O termo é comparado com o nome do grupo e com o seu distinguished name, sem distinção entre maiúsculas e minúsculas, e basta uma correspondência. Deliberadamente, não é comparado com o valor da própria claim: com o formato do nome do grupo definido como id, esse valor é um identificador interno, e alterar o formato esvaziaria de outro modo a claim sem aviso. Deixe o filtro vazio para continuar a enviar tudo.

As expressões regulares não são oferecidas deliberadamente: o filtro é executado em cada início de sessão contra cada grupo do utilizador, onde um padrão patológico abrandaria ou bloquearia o processo de início de sessão.

Proprietários da aplicação (obsoleto)

Obsoleto: Os proprietários da aplicação deixaram de conceder direitos de administração; a administração delegada funciona através de Workspaces. Os proprietários continuam a contar apenas para a definição obsoleta Os proprietários gerem o acesso.

Os proprietários gerem o acesso (obsoleto): onde esta definição foi ativada (desde a versão 26.2), continua a funcionar. Apenas os proprietários da aplicação (seja qual for o seu nível de acesso), os administradores completos e, dentro de um workspace, os seus membros com Gerir acessos podem então conceder ou revogar o acesso, e a API de gestão não pode alterar as atribuições da aplicação. O separador owners só aparece enquanto a definição estiver ativa: lista os proprietários, permite remover um deles e permite desativar a definição. A desativação remove também os proprietários, e a definição não pode voltar a ser ativada. Enquanto alguma aplicação ainda a utilizar, a lista de aplicações mostra um aviso.

Para controlar quem pode atribuir ou revogar o acesso a uma aplicação, adicione-a a um workspace e ative Os membros do workspace gerem o acesso. Só os membros do workspace com a permissão Gerir acessos (bem como os responsáveis e os administradores completos) podem então atribuir a aplicação ou alterar a filiação dos grupos do workspace. Os administradores completos nunca ficam bloqueados. Permitir que os utilizadores peçam acesso através de um fluxo de aprovação continua a funcionar em qualquer caso.

Para os níveis de acesso em que isto se baseia, consulte Utilizadores da consola de administração.

Rodar um client secret

Para aplicações OIDC confidenciais, pode rodar o client secret a qualquer momento a partir de definições gerais → Ações destrutivas da aplicação:

  1. Escolha Rodar secret e confirme escrevendo o nome da aplicação.
  2. A plataforma gera imediatamente um novo secret; o secret antigo deixa de funcionar de imediato.
  3. Revele e copie o novo secret e atualize-o na configuração da própria aplicação.

Como a rotação invalida instantaneamente o secret anterior, planeie uma breve janela de manutenção ou utilize-a durante uma implementação que adote o novo valor. Rodar o secret não quebra a integração em si; apenas o secret guardado muda.

Credenciais: secret vs. certificado de assinatura

A forma como uma aplicação comprova que a plataforma emitiu os seus tokens depende do protocolo:

  • As aplicações OIDC confidenciais (web, machine-to-machine) têm um client secret. É apresentado mascarado no separador de definições OIDC; revele-o para o copiar. Pode rodá-lo sem voltar a registar a aplicação.
  • As aplicações SAML e WS-Federation utilizam uma chave / certificado de assinatura em vez de um secret. A plataforma assina com ele as Assertions e os tokens, e o SP verifica a assinatura com base no certificado publicado.

As chaves de assinatura subjacentes a estes certificados são assimétricas (chave pública) por predefinição, pelo que os integradores obtêm a chave pública correspondente a partir dos metadados ou do JWKS publicados pela plataforma, em vez de partilharem um secret simétrico. As chaves de assinatura são geridas centralmente; consulte Chaves de assinatura.

Financial-grade API security

Nota: Disponível com as subscrições Advanced e Pro.

Para aplicações que tratam dados de elevado valor (open banking, pagamentos, registos de saúde), um perfil de segurança aplica o comportamento reforçado de um perfil Financial-grade API (FAPI) apenas a essa aplicação. As outras aplicações não são afetadas. São oferecidos dois perfis: FAPI 2.0 Security Profile, descrito abaixo, e FAPI 1.0 Advanced, que se baseia nele e requer a subscrição Pro.

O perfil encontra-se no topo do separador de definições OIDC, acima das definições de protocolo que rege. Utilize Editar junto a Perfil de segurança para o alterar. É oferecido para aplicações confidenciais, porque o perfil exclui client secrets partilhados.

Aproximar-se de um perfil

Não tem de decidir antecipadamente por um perfil. Configure as definições individuais uma de cada vez (autenticação de cliente baseada em chaves, uma chave de cliente, proof of possession, pushed authorization requests, um request object assinado) e ative o perfil quando a aplicação estiver preparada para ele.

Alguns requisitos não são de todo configuráveis. O PKCE, os algoritmos de assinatura PS256 e as respostas de autorização assinadas são aplicados pela plataforma quando o perfil é ativado.

Ativar o perfil seleciona também Private Key JWT se a aplicação ainda utilizar um client secret. A chave pública pode ser registada antes ou depois disso (ver abaixo); enquanto não existir uma chave, a aplicação não pode ser utilizada, e cada tentativa de a utilizar é listada em Problemas.

Selecionar FAPI 2.0 Security Profile impõe, para essa aplicação:

  • Autenticação de cliente baseada em chaves: Private Key JWT (ou mutual TLS, nas implementações que o disponibilizam). Não é aceite um client secret.
  • Access tokens com restrição ao remetente: um access token roubado não pode ser reutilizado por mais ninguém. O proof of possession (DPoP) é ativado e não pode ser desativado; quando são selecionados access tokens vinculados ao certificado (implementações dedicadas), estes substituem-no.
  • Pushed authorization requests: a aplicação envia primeiro os seus parâmetros de autorização à plataforma por back-channel e depois redireciona o utilizador com uma referência curta, em vez de expor os parâmetros no URL do browser.
  • PKCE com o método de challenge S256.
  • Apenas o fluxo authorization code: os fluxos implicit e hybrid são rejeitados.
  • Assinaturas mais fortes: os ID tokens e as client assertions da aplicação utilizam PS256 em vez de RS256.

Os access tokens não fazem parte disto. Um access token JWT é assinado pela API para a qual é emitido, com o Algoritmo de assinatura definido nessa API, cuja predefinição é RS256. O FAPI espera também PS256 ou ES256 para ele. Se uma aplicação com perfil puder aceder a uma API que não utilize nenhum deles, essas APIs são indicadas junto ao perfil no separador de definições OIDC. O algoritmo tem de ser alterado na própria API (consulte APIs), aplicando-se então a todas as aplicações que utilizam essa API.

Quando um perfil está ativo, as definições que fixa mantêm a sua caixa de verificação, mas ficam bloqueadas e marcadas como Imposto: proof of possession e pushed authorization requests permanecem selecionados e não podem ser desmarcados, e os métodos de autenticação de cliente que um perfil não permite ficam desativados. Os request objects assinados permanecem editáveis no FAPI 2.0, que não os exige. O PKCE e o PS256 não têm definição própria; são aplicados com o perfil. Guardar um perfil só falha com uma mensagem explicativa se um requisito não puder ser cumprido de todo, por exemplo numa aplicação pública, que nunca pode satisfazer a autenticação de cliente baseada em chaves.

Um perfil pode ser revertido para Sem perfil a qualquer momento. Aplicar um perfil a uma aplicação que já está em utilização é uma alteração disruptiva para ela: a partir desse momento, o seu cliente tem de enviar pushed authorization requests, um challenge PKCE e proof of possession.

Registar chaves de cliente

O Private Key JWT necessita da chave pública da aplicação para que as suas assertions assinadas possam ser verificadas. As chaves são geridas no cartão Chaves de cliente, na parte inferior do separador de definições OIDC, que oferece duas origens mutuamente exclusivas:

  • Registered keys (apresentadas primeiro): selecione Adicionar chave e cole uma chave pública ou um certificado X.509 codificados em PEM; a chave é guardada de imediato. As chaves RSA têm de ter pelo menos 2048 bits; as chaves EC têm de utilizar a curva P-256.
    • As chaves registadas são listadas numa tabela com nome, thumbprint, tipo de chave, data de adição e, quando aplicável, a expiração do certificado.
    • Pode ser indicado um nome opcional. Vale a pena defini-lo: quando uma chave é substituída, são listadas tanto a antiga como a nova, e o nome é o que as distingue à primeira vista. O thumbprint permanece na sua própria coluna, porque é esse o valor que a aplicação envia com cada assertion; é encurtado para caber na linha, passar o cursor por cima mostra o valor completo, e o valor completo pode ainda ser selecionado e copiado. O diálogo de confirmação indica a chave que está prestes a remover.
    • Se o carregamento foi um certificado, é também apresentada a sua data de expiração, e um certificado expirado é assinalado. Trata-se apenas de informação. A chave continua a funcionar, porque é a chave que verifica as assertions da aplicação, não o certificado que a envolve. Substitua-a quando o certificado tiver expirado.
  • JWKS URI: aponte para um conjunto de chaves que a própria aplicação publica. As chaves são então obtidas a partir daí, o que permite à aplicação rodar as suas próprias chaves sem alterações aqui. O URL tem de utilizar https: através de uma ligação não encriptada, as chaves publicadas poderiam ser substituídas em trânsito, e quem o fizesse poderia autenticar-se como a aplicação.
    • Ao guardar, o URL é obtido uma vez como verificação. Se não for devolvido nenhum conjunto de chaves, o URL é guardado na mesma e um aviso indica o motivo. Isto é intencional, para que um URL possa ser introduzido antes de a aplicação publicar as suas chaves. Enquanto o URL não disponibilizar um conjunto de chaves, a aplicação não pode ser utilizada, e a primeira tentativa de a utilizar é registada em Monitoring.

Para alternar entre as duas, utilize a ligação abaixo da secção: Utilizar um JWKS URI em alternativa sob a tabela de chaves e Introduzir chaves manualmente sob o campo do URI. Registar uma chave remove um JWKS URI guardado, e guardar um JWKS URI remove as chaves registadas, pelo que as duas origens nunca coexistem.

Três definições necessitam de uma chave: Private Key JWT, Mutual TLS (certificado autoassinado) e Exigir um request object assinado. Enquanto uma delas estiver ativada e não estiver registada nem uma chave nem um JWKS URI, o separador de definições OIDC abre com um aviso que leva ao cartão Chaves de cliente. As chaves também podem ser adicionadas antecipadamente, antes de o método ser alterado. Para mutual TLS com um certificado autoassinado, carregue o próprio certificado de cliente em vez de uma chave pública simples: a ligação é autenticada comparando o certificado apresentado com o registado.

A chave privada nunca sai da aplicação.

FAPI 1.0 Advanced

Alguns ecossistemas (em particular, esquemas de open banking mais antigos) exigem o perfil anterior FAPI 1.0 Advanced. Está disponível com a subscrição Pro e acrescenta três requisitos a tudo o que foi indicado acima:

  • Respostas de autorização assinadas (JARM): a resposta a um pedido de autorização é devolvida como um JWT assinado em vez de parâmetros de URL simples, para que a aplicação possa verificar que não foi adulterada no browser. Isto não é opcional para o perfil: uma aplicação com FAPI 1.0 Advanced tem de pedir o response mode JWT; caso contrário, os seus pedidos de autorização são rejeitados.
  • Request objects assinados (JAR): os parâmetros de autorização só são aceites dentro de um JWT assinado com a própria chave da aplicação, e esse JWT não pode ser válido durante mais de uma hora.
  • Access tokens vinculados ao certificado (mTLS): em implementações dedicadas com uma periferia mutual TLS, os access tokens são associados ao certificado de cliente TLS da aplicação, como o perfil exige.

Todos são impostos automaticamente assim que o perfil é selecionado e listados como impostos no separador de definições OIDC. Voltar ao FAPI 2.0 ou a nenhum perfil levanta-os novamente.

Nota: Em implementações sem uma periferia mutual TLS, os access tokens neste perfil são associados com DPoP, que o próprio perfil não aceita. Contacte o suporte se uma integração tiver de ser certificada contra o perfil completo.

Certificados de assinatura e encriptação

As aplicações SAML e WS-Federation utilizam um certificado que a plataforma gera automaticamente quando a aplicação é criada. Não o edita diretamente; o certificado público, a impressão digital e um URL de metadados são apresentados só de leitura para que os possa entregar à aplicação.

Se um certificado estiver perto de expirar ou precisar de o renovar, utilize Renovar certificado em Ações destrutivas. A aplicação tem então de ser atualizada com o novo certificado (ou volte a importar o URL de metadados). As chaves de assinatura subjacentes a estes certificados são geridas centralmente; consulte Chaves de assinatura.

Durações de tokens e logout

  • OIDC: defina o Tempo de vida do token de ID e uma Idade máxima da autenticação opcional (que força uma nova autenticação quando a sessão é mais antiga do que o limite). Configure o comportamento de logout através dos Post-logout redirect URIs e do Back-channel logout URI.
  • SAML: a validade das Assertions é controlada pela plataforma; configure o Single Logout através do URL SLO do Service Provider.
  • WS-Federation: defina a duração do token diretamente na aplicação.

As durações dos tokens machine-to-machine e de API são regidas pela API que protege; consulte APIs.

Atribuir aplicações a utilizadores

Registar uma aplicação não concede acesso a ninguém. Decide quem a pode utilizar no separador atribuições da aplicação, onde a pode atribuir a:

  • utilizadores individuais,
  • grupos; consulte Grupos,
  • diretórios inteiros; consulte Diretórios de utilizadores,
  • organizações (com o add-on CIAM): isto adiciona a aplicação ao conjunto aprovado da organização; os seus administradores recebem-na automaticamente, enquanto os outros membros são autorizados individualmente.

Os utilizadores atribuídos diretamente são listados por público: Colaboradores e Customers têm cada um a sua própria secção e contagem no separador, e qualquer um pode ser revogado aí. A concessão a partir daqui só é oferecida para colaboradores, e o seletor está limitado a eles.

Os utilizadores externos não recebem uma aplicação um a um. Chegam a ela através do seu diretório, de um grupo ou, como membros de uma organização, através da autorização individual limitada às aplicações aprovadas para essa organização. Deliberadamente, não existe nenhuma concessão por utilizador fora desse conjunto aprovado, tanto para clientes empresariais como para consumidores.

A revogação nunca é restringida: uma atribuição existente pode sempre ser removida, incluindo uma que não poderia ser criada segundo as regras atuais. É isso que permite limpar as atribuições de um tenant atualizado a partir de uma regra mais antiga.

Cada atribuição pode ter opcionalmente uma data de início e uma data de expiração, para que o acesso comece ou termine automaticamente. As atribuições também determinam o aprovisionamento: um utilizador só é aprovisionado numa aplicação a jusante enquanto tiver uma atribuição ativa.

É a atribuição que rege o acesso: não existe nenhum interruptor de método de início de sessão por aplicação. Os métodos de início de sessão que um utilizador vê são decididos pelo diretório ou pela ligação a que pertence, e não por um interruptor na aplicação.

Nota: Consoante a sua subscrição, pode permitir que os utilizadores peçam acesso a uma aplicação por si próprios e encaminhar esses pedidos através de um fluxo de aprovação, em vez de os atribuir diretamente. Consulte Políticas de autenticação e de atribuição por aplicação.

Nota: Quando uma aplicação pertence a um workspace com Os membros do workspace gerem o acesso ativado, apenas os membros do workspace com a permissão Gerir acessos (bem como os responsáveis e os administradores completos) podem atribuir ou revogar o seu acesso.

Políticas de autenticação e de atribuição por aplicação

No separador políticas da aplicação, define duas coisas independentes: o nível de autenticação exigido aos utilizadores para chegarem à aplicação e se as atribuições necessitam de um fluxo de aprovação.

Requisito de autenticação: escolha um:

  • Predefinição: utilizar os requisitos de autenticação padrão da plataforma.
  • Always require MFA: cada início de sessão nesta aplicação exige um segundo fator.
  • Apply an authentication policy: associar uma política de acesso condicional que decide quando é necessária uma autenticação reforçada ou MFA, com base em sinais como a localização na rede, a hora ou o risco. Consulte Políticas de autenticação.

Políticas de atribuição (requerem o add-on de workflows):

  • Users may request access: os utilizadores pedem esta aplicação por si próprios através de um fluxo de aprovação self-service, em vez de aguardarem que um administrador a atribua, com referência a um fluxo de aprovação que seleciona.

Para restringir quem pode atribuir esta aplicação, coloque-a num workspace com acesso gerido. Para os fatores disponíveis e o funcionamento da autenticação reforçada, consulte Autenticação multifator.

Adicionar aprovisionamento ao SSO

O Single Sign-On e o aprovisionamento de saída são interruptores independentes na mesma aplicação. Configure primeiro o SSO para que os utilizadores possam iniciar sessão e, opcionalmente, ative depois o Aprovisionamento de aplicações para que a plataforma também crie e mantenha contas na aplicação ligada. Pode utilizar qualquer um isoladamente ou ambos em conjunto.

Referência

TermoSignificado
Client IDO identificador público da aplicação na plataforma.
Client secretA credencial confidencial que uma aplicação web ou machine-to-machine utiliza para se autenticar.
Public clientUma aplicação (single-page, nativa, device) que não consegue manter um secret e utiliza PKCE em alternativa.
Token exchangeUm grant OIDC que troca um token por outro para que um serviço possa chamar a jusante como o utilizador original.
Redirect URIUm URL permitido para o qual a plataforma pode devolver o utilizador após o início de sessão; correspondência exata.
URL ACSO endpoint do Service Provider SAML que recebe as Assertions.
RealmO identificador da Relying Party WS-Federation.
ProprietárioUm utilizador responsável por uma aplicação; combina com o acesso de administração delegado limitado aos próprios recursos.
AtribuiçãoUma concessão que permite a um utilizador, grupo, diretório ou organização utilizar uma aplicação, opcionalmente limitada no tempo.

Resolução de problemas

  • A aplicação comunica uma incompatibilidade de redirect URI. Os redirect URIs são comparados de forma exata, incluindo esquema, anfitrião, porta, caminho e barra final. Adicione à lista de redirect URIs o URI exato que a aplicação envia (verifique o respetivo pedido). Não são aceites wildcards.
  • O início de sessão falha logo após rodar o client secret. O secret antigo deixa de funcionar imediatamente quando o roda. Atualize o secret na configuração da aplicação e certifique-se de que está apenas um secret em utilização de cada vez.
  • O início de sessão SAML falha com um erro de assinatura ou de certificado. Confirme que o Service Provider confia no certificado de assinatura atual e que o seu relógio está sincronizado. Uma grande diferença de relógio entre os dois sistemas faz com que as Assertions pareçam expiradas ou ainda não válidas.
  • Um utilizador não consegue ver nem abrir a aplicação. O acesso é concedido, não automático. Atribua a aplicação ao utilizador (diretamente ou através de um grupo, diretório ou organização). Sem uma atribuição, a aplicação não aparece no iniciador do utilizador e o início de sessão interativo é recusado.

Consulte também o glossário.

Nesta página