// Module included in the following assemblies:
//
// assembly-configuring.adoc

[id='con-authentication-services-{context}']
= Authentication services

Authentication services are used to configure the authentication and authorization endpoints
available to messaging clients. The authentication services are configured by the {ProductName}
service operator, and are specified when creating an address space.

An authentication service has a type, which can either be `none`, `standard`, or `external`. The
`none` authentication service type allows all clients to send and receive messages to any address.

The `standard` authentication service type uses a {AuthProductName} instance to store user
credentials and access policies. This authentication service also allows managing users using the
`MessagingUser` custom resource.

The `external` authentication service allows configuring an external provider of authentication and
authorization policies through an AMQP SASL handshake. This can be used to implement a bridge for
your existing identity management system.

Authentication services are configured as custom resources. The following example shows an
authentication service of type `standard`:

[source,yaml,options="nowrap"]
----
apiVersion: admin.enmasse.io/v1beta1
kind: AuthenticationService
metadata:
  name: standard
spec:
  type: standard <1>
  standard:
    credentialsSecret: <2>
      name: my-admin-credentials
    certificateSecret <3>
      name: my-authservice-certificate
    resources: <4>
      requests:
        memory: 2Gi
      limits:
        memory: 2Gi
    storage: <5>
      type: persistent-claim
      size: 5Gi
    datasource: <6>
      type: postgresql
      host: example.com
      port: 5432
      database: authdb
----
<1> The type can be specified as `none`, `standard`, or `external`.
<2> (Optional) The secret must contain the `admin.username` field for the user and the `admin.password` field for the password of the {AuthProductName} admin user. If not specified, a random password will be generated and stored in a secret.
<3> (Optional on OpenShift) A custom certificate can be specified. On OpenShift, a certificate is automatically created if not specified.
<4> (Optional) Resource limits for the {AuthProductName} instance can be specified.
<5> (Optional) The storage type can be specified as `ephemeral` or `persistent-claim`. For `persistent-claim`, you should also configure the size of the claim. The default type is `ephemeral`.
<6> (Optional) Specifies the data source to be used by {AuthProductName}. The default option is the embedded `h2` data source. For production usage, the `postgresql` data source is recommended.

An `external` authentication service can be configured using the following example:

[source,yaml,options="nowrap"]
----
apiVersion: admin.enmasse.io/v1beta1
kind: AuthenticationService
metadata:
  name: my-im-system
spec:
  type: external
  realm: myrealm <1>
  external:
    host: example.com <2>
    port: 5671 <3>
    caCertSecret: <4>
      name: my-ca-cert
----
<1> (Optional) The `realm` is passed in the authentication request. If not specified, an identifier in the form of _namespace-addressspace_ is used as the realm.
<2> The host name of the external authentication service.
<3> The port of the external authentication service.
<4> (Optional) The CA certificate to trust when connecting to the authentication service.

The external authentication service must implement the API described in link:{BookUrlBase}{BaseProductVersion}{BookNameUrl}#con-external-authentication-service-api-messaging[External authentication service API].

