Skip to content

Commit d785f2e

Browse files
smccarthy-iedependabot[bot]
authored and
EricWittmann
committed
docs: configure registry auth and authz with azure ad (#4295)
* docs: how to configure registry auth and authn with ms azure ad * build(deps-dev): bump the ui-dependencies group (#4292) Bumps the ui-dependencies group in /ui/tests with 2 updates: [@playwright/test](https://github.com/microsoft/playwright) and [@types/node](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/node). Updates `@playwright/test` from 1.41.1 to 1.41.2 - [Release notes](https://github.com/microsoft/playwright/releases) - [Commits](microsoft/playwright@v1.41.1...v1.41.2) Updates `@types/node` from 20.11.15 to 20.11.16 - [Release notes](https://github.com/DefinitelyTyped/DefinitelyTyped/releases) - [Commits](https://github.com/DefinitelyTyped/DefinitelyTyped/commits/HEAD/types/node) --- updated-dependencies: - dependency-name: "@playwright/test" dependency-type: direct:development update-type: version-update:semver-patch dependency-group: ui-dependencies - dependency-name: "@types/node" dependency-type: direct:development update-type: version-update:semver-patch dependency-group: ui-dependencies ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * docs: add missing config steps and clean up formatting --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
1 parent d9bcebb commit d785f2e

6 files changed

+125
-12
lines changed

‎docs/modules/ROOT/nav.adoc

+1
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
* Migration
1010
** xref:getting-started/assembly-migrating-registry-v1-v2.adoc[]
1111
* Configuration
12+
** xref:getting-started/assembly-configuring-registry-security.adoc[]
1213
** xref:getting-started/assembly-configuring-the-registry.adoc[]
1314
* Client applications
1415
** xref:getting-started/assembly-managing-registry-artifacts-ui.adoc[]

‎docs/modules/ROOT/pages/getting-started/assembly-configuring-registry-security.adoc

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// Metadata created by nebel
2+
include::{mod-loc}shared/all-attributes.adoc[]
3+
4+
[id="configuring-registry-security_{context}"]
5+
= Configuring {registry} security options
6+
7+
[role="_abstract"]
8+
This chapter explains how to set configuration options for {registry} security. For example, this includes authentication in {keycloak} or Microsoft Azure Active Directory and role-based authorization in {registry}.
9+
10+
* xref:registry-security-keycloak_{context}[]
11+
* xref:registry-security-azure_{context}[]
12+
* xref:registry-security-settings_{context}[]
13+
14+
NOTE: For a list of all available configuration options, see {registry-config-reference}.
15+
16+
//INCLUDES
17+
include::{mod-loc}getting-started/proc-configuring-registry-security-keycloak.adoc[leveloffset=+1]
18+
include::{mod-loc}getting-started/proc-configuring-registry-security-azure.adoc[leveloffset=+1]
19+
include::{mod-loc}getting-started/ref-registry-security-configuration.adoc[leveloffset=+1]

‎docs/modules/ROOT/pages/getting-started/assembly-configuring-the-registry.adoc

+2-6
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,8 @@ include::{mod-loc}shared/all-attributes.adoc[]
55
= Configuring your {registry} deployment
66

77
[role="_abstract"]
8-
This chapter explains how to set important configuration options for {registry}. This includes features such as authentication and authorization, logging, events, and health checks:
8+
This chapter explains how to set important configuration options for your {registry} deployment. This includes features such as the {registry} web console, logging, events, and health checks:
99

10-
* xref:registry-security_{context}[]
11-
* xref:registry-security-settings_{context}[]
1210
ifdef::apicurio-registry[]
1311
* xref:configuring-registry-ui_{context}[]
1412
endif::[]
@@ -17,11 +15,9 @@ endif::[]
1715
* xref:configuring-liveness-readiness-probes_{context}[]
1816
* xref:registry-liveness-env-vars_{context}[]
1917

20-
NOTE: For a list of available configuration options, see {registry-config-reference}.
18+
NOTE: For a list of all available configuration options, see {registry-config-reference}.
2119

2220
//INCLUDES
23-
include::{mod-loc}getting-started/proc-configuring-registry-security.adoc[leveloffset=+1]
24-
include::{mod-loc}getting-started/ref-registry-security-configuration.adoc[leveloffset=+1]
2521
ifdef::apicurio-registry[]
2622
include::{mod-loc}getting-started/proc-configuring-registry-ui.adoc[leveloffset=+1]
2723
endif::[]

‎docs/modules/ROOT/partials/getting-started/proc-configuring-registry-security-azure.adoc

+97
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
// Metadata created by nebel
2+
3+
[id="registry-security-azure_{context}"]
4+
5+
= Configuring {registry} authentication and authorization with Microsoft Azure Active Directory
6+
7+
[role="_abstract"]
8+
This section explains how to manually configure authentication and authorization options for {registry} and Microsoft Azure Active Directory (Azure AD).
9+
10+
The {registry} web console and core REST API support authentication in Azure AD based on OpenID Connect (OIDC) and the OAuth Authorization Code Flow. {registry} provides role-based authorization for default admin, write, and read-only user roles. {registry} authentication and authorization settings are disabled by default.
11+
12+
To secure {registry} with Azure AD, you require a valid directory in Azure AD with specific configuration. This involves registering the {registry} application in the Azure AD portal with recommended settings and configuring environment variables in {registry}.
13+
14+
.Prerequisites
15+
* Azure AD is installed and running. For more details, see the link:https://learn.microsoft.com/en-us/azure[Microsoft Azure AD user documentation].
16+
* {registry} is installed and running.
17+
18+
.Procedure
19+
20+
. Log in to the Azure AD portal using your email address or GitHub account.
21+
22+
. In the navigation menu, select *Manage > App registrations > New registration*, and complete the following settings:
23+
+
24+
** *Name*: Enter your application name. For example: `apicurio-registry-example`
25+
** *Supported account types*: Click *Accounts in any organizational directory*.
26+
** *Redirect URI*: Select *Single-page application* from the list, and enter your {registry} web console application host. For example: `\https://test-registry.com/ui/`
27+
+
28+
IMPORTANT: You must register your {registry} application host as a *Redirect URI*. When logging in, users are redirected from {registry} to Azure AD for authentication, and you want to send them back to your application afterwards. Azure AD does not allow any redirect URLs that are not registered.
29+
30+
. Click *Register*. You can view your app registration details by selecting *Manage > App registrations* > *apicurio-registry-example*.
31+
32+
. Select *Manage > Authentication* and ensure that the application is configured with your redirect URLs and tokens as follows:
33+
** *Redirect URIs*: For example: `\https://test-registry.com/ui/`
34+
** *Implicit grant and hybrid flows*: Click *ID tokens (used for implicit and hybrid flows)*
35+
36+
. Select *Azure AD > Admin > App registrations > Your app > Application (client) ID*. For example: `123456a7-b8c9-012d-e3f4-5fg67h8i901`
37+
38+
. Select *Azure AD > Admin > App registrations > Your app > Directory (tenant) ID*. For example: `\https://login.microsoftonline.com/1a2bc34d-567e-89f1-g0hi-1j2kl3m4no56/v2.0`
39+
40+
. In {registry}, configure the following environment variables with your Azure AD settings:
41+
+
42+
.Configuration for Azure AD settings in {registry}
43+
[.table-expandable,width="100%",cols="6,4,6",options="header"]
44+
|===
45+
|Environment variable
46+
|Description
47+
|Setting
48+
|`KEYCLOAK_API_CLIENT_ID`
49+
|The client application ID for the {registry} REST API
50+
|Your Azure AD Application (client) ID obtained in step 5. For example: `123456a7-b8c9-012d-e3f4-5fg67h8i901`
51+
|`REGISTRY_OIDC_UI_CLIENT_ID`
52+
|The client application ID for the {registry} web console.
53+
|Your Azure AD Application (client) ID obtained in step 5. For example: `123456a7-b8c9-012d-e3f4-5fg67h8i901`
54+
|`REGISTRY_AUTH_URL_CONFIGURED`
55+
|The URL for authentication in Azure AD.
56+
|Your Azure AD Application (tenant) ID obtained in step 6. For example: `\https://login.microsoftonline.com/1a2bc34d-567e-89f1-g0hi-1j2kl3m4no56/v2.0`.
57+
|===
58+
59+
. In {registry}, configure the following environment variables for {registry}-specific settings:
60+
+
61+
.Configuration for {registry}-specific settings
62+
[.table-expandable,width="100%",cols="6,5,4",options="header"]
63+
|===
64+
|Environment variable
65+
|Description
66+
|Setting
67+
|`REGISTRY_AUTH_ENABLED`
68+
|Enables authentication for {registry}.
69+
|`true`
70+
|`REGISTRY_UI_AUTH_TYPE`
71+
|The {registry} authentication type.
72+
|`oidc`
73+
|`CORS_ALLOWED_ORIGINS`
74+
|The host for your {registry} deployment for cross-origin resource sharing (CORS).
75+
|For example: `\https://test-registry.com`
76+
|`REGISTRY_OIDC_UI_REDIRECT_URL`
77+
|The host for your {registry} web console.
78+
|For example: `\https://test-registry.com/ui`
79+
|`ROLE_BASED_AUTHZ_ENABLED`
80+
|Enables role-based authorization in {registry}.
81+
|`true`
82+
|`QUARKUS_OIDC_ROLES_ROLE_CLAIM_PATH`
83+
|The name of the claim in which Azure AD stores roles.
84+
|`roles`
85+
|===
86+
+
87+
NOTE: When you enable roles in {registry}, you must also create the same roles in Azure AD as application roles. The default roles expected by {registry} are `sr-admin`, `sr-developer`, and `sr-readonly`.
88+
89+
90+
[role="_additional-resources"]
91+
.Additional resources
92+
* For details on configuring non-default user role names, see xref:registry-security-settings_{context}[].
93+
* For more details on using Azure AD, see the link:https://learn.microsoft.com/en-us/azure[Microsoft Azure AD user documentation].
94+
95+
96+
97+

‎docs/modules/ROOT/partials/getting-started/proc-configuring-registry-security.adoc ‎docs/modules/ROOT/partials/getting-started/proc-configuring-registry-security-keycloak.adoc

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
// Metadata created by nebel
22

3-
[id="registry-security_{context}"]
3+
[id="registry-security-keycloak_{context}"]
44

55
= Configuring {registry} authentication and authorization with {keycloak}
66

77
[role="_abstract"]
8-
This section explains how to manually configure authentication and authorization options for {registry} using {keycloak}.
8+
This section explains how to manually configure authentication and authorization options for {registry} and {keycloak}.
99

1010
[NOTE]
1111
====
@@ -18,9 +18,9 @@ see xref:registry-security-keycloak[].
1818
endif::[]
1919
====
2020

21-
You can enable authentication for the {registry} web console and core REST API using {keycloak} based on OAuth using OpenID Connect (OIDC). The same {keycloak} realm and users are federated across the {registry} web console and core REST API using OpenID Connect so that you only require one set of credentials.
21+
The {registry} web console and core REST API support authentication in {keycloak} based on OAuth and OpenID Connect (OIDC). The same {keycloak} realm and users are federated across the {registry} web console and core REST API using OpenID Connect so that you only require one set of credentials.
2222

23-
{registry} provides role-based authorization for default admin, write, and read-only user roles. {registry} also provides content-based authorization at the schema or API level, where only the creator of the registry artifact can update or delete it. {registry} authentication and authorization settings are disabled by default.
23+
{registry} provides role-based authorization for default admin, write, and read-only user roles. {registry} provides content-based authorization at the schema or API level, where only the creator of the registry artifact can update or delete it. {registry} authentication and authorization settings are disabled by default.
2424

2525
.Prerequisites
2626
* {keycloak} is installed and running. For more details, see the

‎docs/modules/ROOT/partials/shared/attributes.adoc

+2-2
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ ifndef::service-registry-downstream[]
2626
:registry-docker-version: latest-release
2727
:registry-v1: 1.3
2828
:registry-v1-release: 1.3.2.Final
29-
:operator-version: 1.2.0-dev
29+
:operator-version: 1.1.0-v2.4.12.final
3030
:kafka-streams: Strimzi
3131
:registry-kafka-version: 3.5
3232
:keycloak: Keycloak
@@ -47,7 +47,7 @@ ifdef::service-registry-downstream[]
4747
:registry-version: 2.5
4848
:registry-release: 2.5.4.Final-redhat-00001
4949
:registry-v1-release: 1.3.2.Final-redhat-00002
50-
:operator-version: 1.1.0.redhat.x
50+
:operator-version: 1.2.0.redhat.x
5151
:kafka-streams: AMQ Streams
5252
:registry-streams-version: 2.6
5353
:keycloak: {org-name} Single Sign-On

0 commit comments

Comments
 (0)