diff --git a/.custom_wordlist.txt b/.custom_wordlist.txt index 979397fb..56887d74 100644 --- a/.custom_wordlist.txt +++ b/.custom_wordlist.txt @@ -31,6 +31,7 @@ ARMv async AttributeError AudioTrack +Auth backend balancer balancers @@ -199,6 +200,7 @@ OOB OOM OpenAPI OpenGL +OpenID OpenStack PCI Perfetto diff --git a/howto/install-appliance/enable-oidc.md b/howto/install-appliance/enable-oidc.md new file mode 100644 index 00000000..6c79258e --- /dev/null +++ b/howto/install-appliance/enable-oidc.md @@ -0,0 +1,55 @@ +(howto-appliance-enable-oidc)= +# How to enable custom identity provider support + +The Anbox Cloud Appliance has support for custom identity providers for authentication through the use of [OpenID Connect](https://openid.net/developers/discover-openid-and-openid-connect/). + +Support for a custom identity provider has to be enabled at initialisation by using a preseed configuration. See {ref}`ref-appliance-preseed-config` for more details. + +Anbox Cloud uses the [authorisation code flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) to obtain an identity token. No access token is requested in this flow because authorisation is handled within the Anbox Cloud services. + +In order to allow discovery of the necessary endpoints on the identity provider, it must support the [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) protocol. + +The following will show you how to configure an [OpenID Connect](https://openid.net/developers/discover-openid-and-openid-connect/) based identity provider for the Anbox Cloud Appliance. + +## Preparation + +In order to configure [OpenID Connect](https://openid.net/developers/discover-openid-and-openid-connect/) based authentication, you will need the following from your identity provider: + +* The issuer URL +* The client ID +* (Optional) The audience URL, required by some providers. For example, [Auth0](https://auth0.com) + +The identity provider is expected to provide the JSON Web Key Set endpoint on `/.well-known/jwks.json`. + +Your identity provider must have `https:///oidc/callback` configured as allowed redirect/callback URL. + +## Configure OpenID Connect + +It is only possible to configure support for OpenID Connect only when the Anbox Cloud Appliance is being initialised with a preseed (see {ref}`ref-appliance-preseed-config`). The other steps to install the Anbox Cloud Appliance as described in {ref}`tut-installing-appliance` remain the same. + +The issuer URL, client ID and optional audience URL are set in the preseed configuration as follows: + +```yaml +$ cat preseed.yaml +.... +oidc: + issuer: https://my.auth.com + client_id: aff32f32ffwfsdfdsfdsg + # Only if your identity provider requires it + audience: https://my.auth.com/api/v2 +``` + +With the preseed configuration you can initiate the initialisation process by running: + + sudo anbox-cloud-appliance init --preseed < preseed.yaml + +Once the initialisation has been completed, you can register a new user by running: + + sudo anbox-cloud-appliance dashboard register + +Once the user has been registered by following the printed URL and authenticated with your identity provider, access is granted to the web UI. + +## Related topics + +* {ref}`tut-installing-appliance` +* {ref}`howto-use-web-dashboard` \ No newline at end of file diff --git a/howto/install-appliance/landing.md b/howto/install-appliance/landing.md index da1b8e6a..c35ce6c0 100644 --- a/howto/install-appliance/landing.md +++ b/howto/install-appliance/landing.md @@ -9,6 +9,14 @@ We strongly recommend that you follow the {ref}`tut-installing-appliance` tutori Also, see {ref}`ref-requirements` before you start your installation. +The following additional guides provide you instructions on how to enable certain features of the Anbox Cloud Appliance: + +```{toctree} +:titlesonly: + +Enable support for custom identity provider +``` + ## Supported cloud platforms The Anbox Cloud Appliance is currently available for the following cloud platforms: diff --git a/reference/appliance-preseed.md b/reference/appliance-preseed.md index 30850250..162526ec 100644 --- a/reference/appliance-preseed.md +++ b/reference/appliance-preseed.md @@ -48,5 +48,16 @@ lxd: project: anbox-cloud ams: api: + # List of UIDs which are allowed to talk to the AMS UNIX domain + # socket. In this example both UID 0 (root) and 1000 are allowed + # to connect to AMS. All other users will be denied. allowed-uids: [0, 1000] +oidc: + # OpenID Connect issuer URL + issuer: https://my.auth.com + # OpenID Connect client ID + client_id: afeff2f23f23f32f23f2 + # (optional) OpenID Connect audience URL, as required by some + # providers. + audience: https://my.auth.com/api/v2 ``` \ No newline at end of file