> ## Documentation Index
> Fetch the complete documentation index at: https://docs.niadra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configurar o SSO

> Cria ou troca a conexão: domínios, grupos que dão papéis, papel padrão e as regras do login.



## OpenAPI

````yaml openapi/pt/control.json PUT /v1/sso
openapi: 3.1.0
info:
  title: API de controle da Niadra
  version: '1'
  description: >-
    Tenants, projetos, fontes, chaves, pessoas, configuração e uso. Nunca recebe
    conteúdo de cliente.
servers:
  - url: https://control.api.niadra.com
security: []
paths:
  /v1/sso:
    put:
      summary: Configurar o SSO
      description: >-
        Cria ou troca a conexão do tenant, OIDC ou SAML. Um emissor OIDC é
        conferido pelo documento de descoberta dele; um certificado SAML precisa
        ser válido. Um domínio que outro tenant usa responde 409. Exige o papel
        admin.


        **Autenticação.** Token de pessoa emitido pelo controle (`Authorization:
        Bearer <JWT>`), com o papel que a operação pede.
      operationId: put_sso_v1_sso_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SsoConnectionIn'
            example:
              protocol: oidc
              domains:
                - acme.example
              enabled: true
              enforced: false
              default_role: null
              role_mappings:
                - group: niadra-admins
                  role: admin
                - group: cx-quality
                  role: review
              groups_attribute: groups
              require_second_factor: false
              oidc:
                issuer: https://login.acme.example
                client_id: niadra-console
                client_secret: the-client-secret-from-the-provider
                scopes:
                  - groups
              reason: The Console signs in with the company login
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SsoOut'
              example:
                connection:
                  connection_id: 0192f8e5-93a4-75b6-8fc7-3c4d5e6f7a89
                  protocol: oidc
                  domains:
                    - acme.example
                  enabled: true
                  enforced: false
                  default_role: null
                  role_mappings:
                    - group: niadra-admins
                      role: admin
                    - group: cx-quality
                      role: review
                  groups_attribute: groups
                  require_second_factor: false
                  oidc:
                    issuer: https://login.acme.example
                    client_id: niadra-console
                    scopes:
                      - openid
                      - email
                      - profile
                      - groups
                    client_secret_set: true
                  saml: null
                  created_at: '2026-09-24T10:00:00Z'
                  updated_at: '2026-09-24T10:00:00Z'
                  updated_by: 0192f0a0-4e5f-7061-9c72-8d9e0f1a2b34
                service_provider:
                  oidc_redirect_uri: https://control.api.niadra.com/v1/auth/sso/oidc/callback
                  saml_entity_id: urn:niadra:sso:0192f0a0-1b2c-7d3e-8f40-5a6b7c8d9e01
                  saml_acs_url: >-
                    https://control.api.niadra.com/v1/auth/sso/saml/0192f0a0-1b2c-7d3e-8f40-5a6b7c8d9e01/acs
                  saml_metadata_url: >-
                    https://control.api.niadra.com/v1/auth/sso/saml/0192f0a0-1b2c-7d3e-8f40-5a6b7c8d9e01/metadata
          description: >-
            A conexão como ficou guardada, e o que colar no provedor de
            identidade.
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: O pedido não bate com o contrato.
      security:
        - personToken: []
components:
  schemas:
    SsoConnectionIn:
      additionalProperties: false
      properties:
        default_role:
          anyOf:
            - $ref: '#/components/schemas/Role'
            - type: 'null'
          description: >-
            Para quem não está em nenhum grupo mapeado; nulo deixa entrar só
            quem está num grupo mapeado.
        domains:
          description: >-
            Os domínios de e-mail cujas pessoas entram por esta conexão. Cada
            domínio é de um tenant só; e-mails públicos (gmail.com e parecidos)
            são recusados.
          items:
            type: string
          maxItems: 20
          minItems: 1
          title: Domains
          type: array
        enabled:
          default: true
          title: Enabled
          type: boolean
        enforced:
          default: false
          description: >-
            Pessoas dos domínios entram só pelo SSO. Quem é admin no tenant
            inteiro mantém a senha, como acesso quando o provedor falha.
          title: Enforced
          type: boolean
        groups_attribute:
          default: groups
          description: A declaração (OIDC) ou o atributo (SAML) que traz os grupos.
          maxLength: 256
          minLength: 1
          title: Groups Attribute
          type: string
        oidc:
          anyOf:
            - $ref: '#/components/schemas/OidcIn'
            - type: 'null'
        protocol:
          $ref: '#/components/schemas/SsoProtocol'
        reason:
          description: O motivo, guardado no histórico de acesso do tenant.
          maxLength: 1000
          minLength: 3
          title: Reason
          type: string
        require_second_factor:
          default: false
          description: >-
            Pede o código do autenticador da Niadra depois do provedor, além do
            MFA do provedor.
          title: Require Second Factor
          type: boolean
        role_mappings:
          items:
            $ref: '#/components/schemas/RoleMappingModel'
          maxItems: 100
          title: Role Mappings
          type: array
        saml:
          anyOf:
            - $ref: '#/components/schemas/SamlIn'
            - type: 'null'
      required:
        - protocol
        - domains
        - reason
      title: SsoConnectionIn
      type: object
    SsoOut:
      additionalProperties: false
      properties:
        connection:
          anyOf:
            - $ref: '#/components/schemas/SsoConnectionOut'
            - type: 'null'
          description: Nulo enquanto o tenant não tem conexão.
        service_provider:
          $ref: '#/components/schemas/ServiceProviderOut'
      required:
        - connection
        - service_provider
      title: SsoOut
      type: object
    Problem:
      additionalProperties: false
      description: >-
        Detalhes do problema no formato da RFC 9457; `code` vem do catálogo de
        erros versionado.
      properties:
        code:
          title: Code
          type: string
        detail:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Detail
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Request Id
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          default: about:blank
          title: Type
          type: string
      required:
        - title
        - status
        - code
      title: Problem
      type: object
    Role:
      description: Papéis do Console, combináveis.
      enum:
        - admin
        - security
        - integration
        - review
        - analysis
        - vendor
      title: Role
      type: string
    OidcIn:
      additionalProperties: false
      properties:
        client_id:
          maxLength: 512
          minLength: 1
          title: Client Id
          type: string
        client_secret:
          anyOf:
            - maxLength: 2048
              type: string
            - type: 'null'
          description: >-
            Obrigatório quando a conexão é criada ou passa a ser OIDC; nulo
            mantém o guardado. Nunca volta nas respostas: fica guardado cifrado
            com a chave do plano de controle.
          title: Client Secret
        issuer:
          description: >-
            O emissor do provedor, com https. A Niadra lê
            `<issuer>/.well-known/openid-configuration`.
          maxLength: 2048
          minLength: 9
          title: Issuer
          type: string
        scopes:
          description: >-
            Escopos além de `openid email profile`, que vão sempre, como
            `groups`.
          items:
            type: string
          maxItems: 20
          title: Scopes
          type: array
      required:
        - issuer
        - client_id
      title: OidcIn
      type: object
    SsoProtocol:
      enum:
        - oidc
        - saml
      title: SsoProtocol
      type: string
    RoleMappingModel:
      additionalProperties: false
      properties:
        group:
          description: >-
            Um valor da declaração (OIDC) ou do atributo (SAML) de grupos: o
            nome de um grupo, ou um id, como o id de objeto que o Microsoft
            Entra ID manda. A comparação ignora maiúsculas.
          maxLength: 256
          minLength: 1
          title: Group
          type: string
        role:
          $ref: '#/components/schemas/Role'
          description: Vale no tenant inteiro. O papel vendor nunca vem de um grupo.
      required:
        - group
        - role
      title: RoleMappingModel
      type: object
    SamlIn:
      additionalProperties: false
      properties:
        idp_certificate:
          description: >-
            O certificado que assina as asserções, em PEM ou o conteúdo em
            base64 dos metadados.
          maxLength: 20000
          minLength: 100
          title: Idp Certificate
          type: string
        idp_entity_id:
          description: O entity ID (emissor) do provedor.
          maxLength: 1024
          minLength: 1
          title: Idp Entity Id
          type: string
        idp_sso_url:
          description: >-
            O endereço de login do provedor para o binding HTTP-Redirect, com
            https.
          maxLength: 2048
          minLength: 9
          title: Idp Sso Url
          type: string
      required:
        - idp_entity_id
        - idp_sso_url
        - idp_certificate
      title: SamlIn
      type: object
    SsoConnectionOut:
      additionalProperties: false
      properties:
        connection_id:
          format: uuid
          title: Connection Id
          type: string
        created_at:
          format: date-time
          title: Created At
          type: string
        default_role:
          anyOf:
            - $ref: '#/components/schemas/Role'
            - type: 'null'
        domains:
          items:
            type: string
          title: Domains
          type: array
        enabled:
          title: Enabled
          type: boolean
        enforced:
          title: Enforced
          type: boolean
        groups_attribute:
          title: Groups Attribute
          type: string
        oidc:
          anyOf:
            - $ref: '#/components/schemas/OidcOut'
            - type: 'null'
        protocol:
          $ref: '#/components/schemas/SsoProtocol'
        require_second_factor:
          title: Require Second Factor
          type: boolean
        role_mappings:
          items:
            $ref: '#/components/schemas/RoleMappingModel'
          title: Role Mappings
          type: array
        saml:
          anyOf:
            - $ref: '#/components/schemas/SamlOut'
            - type: 'null'
        updated_at:
          format: date-time
          title: Updated At
          type: string
        updated_by:
          format: uuid
          title: Updated By
          type: string
      required:
        - connection_id
        - protocol
        - domains
        - enabled
        - enforced
        - default_role
        - role_mappings
        - groups_attribute
        - require_second_factor
        - oidc
        - saml
        - created_at
        - updated_at
        - updated_by
      title: SsoConnectionOut
      type: object
    ServiceProviderOut:
      additionalProperties: false
      description: O que colar no provedor de identidade.
      properties:
        oidc_redirect_uri:
          description: 'OIDC: a URI de redirecionamento (callback) da aplicação.'
          title: Oidc Redirect Uri
          type: string
        saml_acs_url:
          description: 'SAML: o assertion consumer service, no binding HTTP-POST.'
          title: Saml Acs Url
          type: string
        saml_entity_id:
          description: 'SAML: o entity ID do provedor de serviço (o público da asserção).'
          title: Saml Entity Id
          type: string
        saml_metadata_url:
          description: >-
            SAML: os metadados do provedor de serviço, depois que a conexão
            existe.
          title: Saml Metadata Url
          type: string
      required:
        - oidc_redirect_uri
        - saml_entity_id
        - saml_acs_url
        - saml_metadata_url
      title: ServiceProviderOut
      type: object
    OidcOut:
      additionalProperties: false
      properties:
        client_id:
          title: Client Id
          type: string
        client_secret_set:
          description: 'Sempre verdadeiro: o segredo em si nunca volta.'
          title: Client Secret Set
          type: boolean
        issuer:
          title: Issuer
          type: string
        scopes:
          items:
            type: string
          title: Scopes
          type: array
      required:
        - issuer
        - client_id
        - scopes
        - client_secret_set
      title: OidcOut
      type: object
    SamlOut:
      additionalProperties: false
      properties:
        certificate:
          $ref: '#/components/schemas/CertificateOut'
        idp_entity_id:
          title: Idp Entity Id
          type: string
        idp_sso_url:
          title: Idp Sso Url
          type: string
      required:
        - idp_entity_id
        - idp_sso_url
        - certificate
      title: SamlOut
      type: object
    CertificateOut:
      additionalProperties: false
      properties:
        not_after:
          format: date-time
          title: Not After
          type: string
        pem:
          description: >-
            O certificado como está guardado: é público, e o Console o mostra
            para o próximo salvamento.
          title: Pem
          type: string
        sha256_fingerprint:
          title: Sha256 Fingerprint
          type: string
        subject:
          title: Subject
          type: string
      required:
        - subject
        - not_after
        - sha256_fingerprint
        - pem
      title: CertificateOut
      type: object
  securitySchemes:
    personToken:
      type: http
      scheme: bearer
      bearerFormat: JWT

````