> ## 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. # Set up SSO > Creates or replaces the connection: domains, groups that give roles, default role and the sign-in rules. ## OpenAPI ````yaml openapi/en/control.json PUT /v1/sso openapi: 3.1.0 info: title: Niadra control API version: '1' description: >- Tenants, projects, sources, keys, people, configuration and usage. It never receives customer content. servers: - url: https://control.api.niadra.com security: [] paths: /v1/sso: put: summary: Set up SSO description: >- Creates or replaces the tenant's connection, OIDC or SAML. An OIDC issuer is checked against its discovery document; a SAML certificate must parse. A domain another tenant uses answers 409. Needs the admin role. **Authentication.** Person token issued by the control plane (`Authorization: Bearer `), with the role the operation needs. 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: >- The connection as stored, and what to paste into the identity provider. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: The request does not match the contract. security: - personToken: [] components: schemas: SsoConnectionIn: additionalProperties: false properties: default_role: anyOf: - $ref: '#/components/schemas/Role' - type: 'null' description: >- For a person in no mapped group; null lets in only people of mapped groups. domains: description: >- The e-mail domains whose people sign in through this connection. Each domain belongs to one tenant; public mailboxes (gmail.com and the like) are refused. items: type: string maxItems: 20 minItems: 1 title: Domains type: array enabled: default: true title: Enabled type: boolean enforced: default: false description: >- People of the domains sign in only through SSO. A tenant-wide admin keeps the password, as the way in when the provider fails. title: Enforced type: boolean groups_attribute: default: groups description: The claim (OIDC) or attribute (SAML) that carries the groups. maxLength: 256 minLength: 1 title: Groups Attribute type: string oidc: anyOf: - $ref: '#/components/schemas/OidcIn' - type: 'null' protocol: $ref: '#/components/schemas/SsoProtocol' reason: description: Why, kept in the tenant's access history. maxLength: 1000 minLength: 3 title: Reason type: string require_second_factor: default: false description: >- Ask for the Niadra authenticator code after the provider, on top of the provider's MFA. 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: Null while the tenant has no connection. service_provider: $ref: '#/components/schemas/ServiceProviderOut' required: - connection - service_provider title: SsoOut type: object Problem: additionalProperties: false description: RFC 9457 problem details; `code` comes from the versioned error catalog. 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: Console roles, combinable. 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: >- Required when the connection is created or moves to OIDC; null keeps the one stored. Never returned: it is stored sealed with the control plane's key. title: Client Secret issuer: description: >- The provider's issuer, https. Niadra reads `/.well-known/openid-configuration`. maxLength: 2048 minLength: 9 title: Issuer type: string scopes: description: >- Scopes beyond `openid email profile`, which always go, such as `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: >- A value of the groups claim (OIDC) or attribute (SAML): a group name, or an id such as the object id Microsoft Entra ID sends. Compared without case. maxLength: 256 minLength: 1 title: Group type: string role: $ref: '#/components/schemas/Role' description: >- Given on the whole tenant. The vendor role is never given by a group. required: - group - role title: RoleMappingModel type: object SamlIn: additionalProperties: false properties: idp_certificate: description: >- The certificate that signs the assertions, PEM or the base64 body from the metadata. maxLength: 20000 minLength: 100 title: Idp Certificate type: string idp_entity_id: description: The provider's entity id (issuer). maxLength: 1024 minLength: 1 title: Idp Entity Id type: string idp_sso_url: description: >- The provider's single sign-on address for the HTTP-Redirect binding, 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: What to paste into the identity provider. properties: oidc_redirect_uri: description: 'OIDC: the redirect (callback) URI of the application.' title: Oidc Redirect Uri type: string saml_acs_url: description: 'SAML: the assertion consumer service, HTTP-POST binding.' title: Saml Acs Url type: string saml_entity_id: description: 'SAML: the service provider''s entity id (audience).' title: Saml Entity Id type: string saml_metadata_url: description: 'SAML: the service provider''s metadata, once the connection exists.' 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: 'Always true: the secret itself is never returned.' 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: >- The certificate as stored: public, so the Console shows it for the next save. 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 ````