github.com/argoproj/argo-cd/v3@v3.2.1/docs/operator-manual/user-management/microsoft.md (about) 1 # Microsoft 2 3 !!! note "" 4 Entra ID was formerly known as Azure AD. 5 6 * [Entra ID App Registration Auth using OIDC](#entra-id-app-registration-auth-using-oidc) 7 * [Entra ID SAML Enterprise App Auth using Dex](#entra-id-saml-enterprise-app-auth-using-dex) 8 * [Entra ID App Registration Auth using Dex](#entra-id-app-registration-auth-using-dex) 9 10 ## Entra ID App Registration Auth using OIDC 11 ### Configure a new Entra ID App registration 12 #### Add a new Entra ID App registration 13 14 1. From the `Microsoft Entra ID` > `App registrations` menu, choose `+ New registration` 15 2. Enter a `Name` for the application (e.g. `Argo CD`). 16 3. Specify who can use the application (e.g. `Accounts in this organizational directory only`). 17 4. Enter Redirect URI (optional) as follows (replacing `my-argo-cd-url` with your Argo URL), then choose `Add`. 18 - **Platform:** `Web` 19 - **Redirect URI:** https://`<my-argo-cd-url>`/auth/callback 20 5. When registration finishes, the Azure portal displays the app registration's Overview pane. You see the Application (client) ID. 21  22 23 #### Configure additional platform settings for ArgoCD CLI 24 25 1. In the Azure portal, in App registrations, select your application. 26 2. Under Manage, select Authentication. 27 3. Under Platform configurations, select Add a platform. 28 4. Under Configure platforms, select the "Mobile and desktop applications" tile. Use the below value. You shouldn't change it. 29 - **Redirect URI:** `http://localhost:8085/auth/callback` 30  31 32 #### Add credentials a new Entra ID App registration 33 ##### Using Workload Identity Federation (Recommended) 34 1. **Label the Pods:** Add the `azure.workload.identity/use: "true"` label to the `argocd-server` pods. 35 2. **Add Annotation to Service Account:** Add `azure.workload.identity/client-id: "$CLIENT_ID"` annotation to the `argocd-server` service account using the details from application created in previous step. 36 3. From the `Certificates & secrets` menu, navigate to `Federated credentials`, then choose `+ Add credential` 37 4. Choose `Federated credential scenario` as `Kubernetes Accessing Azure resources` 38 - Enter Cluster Issuer URL, refer to [retrieve the OIDC issuer URL](https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster#retrieve-the-oidc-issuer-url) documentation 39 - Enter namespace as the namespace where the argocd is deployed 40 - Enter service account name as `argocd-server` 41 - Enter a unique name 42 - Click Add. 43 44 ##### Using Client Secret 45 1. From the `Certificates & secrets` menu, choose `+ New client secret` 46 2. Enter a `Name` for the secret (e.g. `ArgoCD-SSO`). 47 - Make sure to copy and save generated value. This is a value for the `client_secret`. 48  49 50 #### Setup permissions for Entra ID Application 51 52 1. From the `API permissions` menu, choose `+ Add a permission` 53 2. Find `User.Read` permission (under `Microsoft Graph`) and grant it to the created application: 54  55 3. From the `Token Configuration` menu, choose `+ Add groups claim` 56  57 58 ### Associate an Entra ID group to your Entra ID App registration 59 60 1. From the `Microsoft Entra ID` > `Enterprise applications` menu, search the App that you created (e.g. `Argo CD`). 61 - An Enterprise application with the same name of the Entra ID App registration is created when you add a new Entra ID App registration. 62 2. From the `Users and groups` menu of the app, add any users or groups requiring access to the service. 63  64 65 ### Configure Argo to use the new Entra ID App registration 66 67 1. Edit `argocd-cm` and configure the `data.oidc.config` and `data.url` section: 68 69 ConfigMap -> argocd-cm 70 71 data: 72 url: https://argocd.example.com/ # Replace with the external base URL of your Argo CD 73 oidc.config: | 74 name: Azure 75 issuer: https://login.microsoftonline.com/{directory_tenant_id}/v2.0 76 clientID: {azure_ad_application_client_id} 77 clientSecret: $oidc.azure.clientSecret // if using client secret for authentication 78 azure: 79 useWorkloadIdentity: true // if using azure workload identity for authentication 80 requestedIDTokenClaims: 81 groups: 82 essential: true 83 value: "ApplicationGroup" 84 requestedScopes: 85 - openid 86 - profile 87 - email 88 89 2. Skip this step if using azure workload identity. Edit `argocd-secret` and configure the `data.oidc.azure.clientSecret` section: 90 91 Secret -> argocd-secret 92 93 data: 94 oidc.azure.clientSecret: {client_secret | base64_encoded} 95 96 3. Edit `argocd-rbac-cm` to configure permissions. Use group ID from Azure for assigning roles 97 [RBAC Configurations](../rbac.md) 98 99 ConfigMap -> argocd-rbac-cm 100 101 policy.default: role:readonly 102 policy.csv: | 103 p, role:org-admin, applications, *, */*, allow 104 p, role:org-admin, clusters, get, *, allow 105 p, role:org-admin, repositories, get, *, allow 106 p, role:org-admin, repositories, create, *, allow 107 p, role:org-admin, repositories, update, *, allow 108 p, role:org-admin, repositories, delete, *, allow 109 g, "84ce98d1-e359-4f3b-85af-985b458de3c6", role:org-admin 110 111 4. Mapping role from jwt token to argo. 112 If you want to map the roles from the jwt token to match the default roles (readonly and admin) then you must change the scope variable in the rbac-configmap. 113 114 policy.default: role:readonly 115 policy.csv: | 116 p, role:org-admin, applications, *, */*, allow 117 p, role:org-admin, clusters, get, *, allow 118 p, role:org-admin, repositories, get, *, allow 119 p, role:org-admin, repositories, create, *, allow 120 p, role:org-admin, repositories, update, *, allow 121 p, role:org-admin, repositories, delete, *, allow 122 g, "84ce98d1-e359-4f3b-85af-985b458de3c6", role:org-admin 123 scopes: '[groups, email]' 124 125 Refer to [operator-manual/argocd-rbac-cm.yaml](https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/argocd-rbac-cm.yaml) for all of the available variables. 126 127 ## Entra ID SAML Enterprise App Auth using Dex 128 ### Configure a new Entra ID Enterprise App 129 130 1. From the `Microsoft Entra ID` > `Enterprise applications` menu, choose `+ New application` 131 2. Select `Non-gallery application` 132 3. Enter a `Name` for the application (e.g. `Argo CD`), then choose `Add` 133 4. Once the application is created, open it from the `Enterprise applications` menu. 134 5. From the `Users and groups` menu of the app, add any users or groups requiring access to the service. 135  136 6. From the `Single sign-on` menu, edit the `Basic SAML Configuration` section as follows (replacing `my-argo-cd-url` with your Argo URL): 137 - **Identifier (Entity ID):** https://`<my-argo-cd-url>`/api/dex/callback 138 - **Reply URL (Assertion Consumer Service URL):** https://`<my-argo-cd-url>`/api/dex/callback 139 - **Sign on URL:** https://`<my-argo-cd-url>`/auth/login 140 - **Relay State:** `<empty>` 141 - **Logout Url:** `<empty>` 142  143 7. From the `Single sign-on` menu, edit the `User Attributes & Claims` section to create the following claims: 144 - `+ Add new claim` | **Name:** email | **Source:** Attribute | **Source attribute:** user.mail 145 - `+ Add group claim` | **Which groups:** All groups | **Source attribute:** Group ID | **Customize:** True | **Name:** Group | **Namespace:** `<empty>` | **Emit groups as role claims:** False 146 - *Note: The `Unique User Identifier` required claim can be left as the default `user.userprincipalname`* 147  148 8. From the `Single sign-on` menu, download the SAML Signing Certificate (Base64) 149 - Base64 encode the contents of the downloaded certificate file, for example: 150 - `$ cat ArgoCD.cer | base64` 151 - *Keep a copy of the encoded output to be used in the next section.* 152 9. From the `Single sign-on` menu, copy the `Login URL` parameter, to be used in the next section. 153 154 ### Configure Argo to use the new Entra ID Enterprise App 155 156 1. Edit `argocd-cm` and add the following `dex.config` to the data section, replacing the `caData`, `my-argo-cd-url` and `my-login-url` your values from the Entra ID App: 157 158 data: 159 url: https://my-argo-cd-url 160 dex.config: | 161 logger: 162 level: debug 163 format: json 164 connectors: 165 - type: saml 166 id: saml 167 name: saml 168 config: 169 entityIssuer: https://my-argo-cd-url/api/dex/callback 170 ssoURL: https://my-login-url (e.g. https://login.microsoftonline.com/xxxxx/a/saml2) 171 caData: | 172 MY-BASE64-ENCODED-CERTIFICATE-DATA 173 redirectURI: https://my-argo-cd-url/api/dex/callback 174 usernameAttr: email 175 emailAttr: email 176 groupsAttr: Group 177 178 2. Edit `argocd-rbac-cm` to configure permissions, similar to example below. 179 - Use Entra ID `Group IDs` for assigning roles. 180 - See [RBAC Configurations](../rbac.md) for more detailed scenarios. 181 182 # example policy 183 policy.default: role:readonly 184 policy.csv: | 185 p, role:org-admin, applications, *, */*, allow 186 p, role:org-admin, clusters, get, *, allow 187 p, role:org-admin, repositories, get, *, allow 188 p, role:org-admin, repositories, create, *, allow 189 p, role:org-admin, repositories, update, *, allow 190 p, role:org-admin, repositories, delete, *, allow 191 g, "84ce98d1-e359-4f3b-85af-985b458de3c6", role:org-admin # (azure group assigned to role) 192 193 ## Entra ID App Registration Auth using Dex 194 195 Configure a new AD App Registration, as above. 196 Then, add the `dex.config` to `argocd-cm`: 197 ```yaml 198 ConfigMap -> argocd-cm 199 200 data: 201 dex.config: | 202 connectors: 203 - type: microsoft 204 id: microsoft 205 name: Your Company GmbH 206 config: 207 clientID: $MICROSOFT_APPLICATION_ID 208 clientSecret: $MICROSOFT_CLIENT_SECRET 209 redirectURI: http://localhost:8080/api/dex/callback 210 tenant: ffffffff-ffff-ffff-ffff-ffffffffffff 211 groups: 212 - DevOps 213 ``` 214 215 ## Validation 216 ### Log in to ArgoCD UI using SSO 217 218 1. Open a new browser tab and enter your ArgoCD URI: https://`<my-argo-cd-url>` 219  220 3. Click `LOGIN VIA AZURE` button to log in with your Microsoft Entra ID account. You’ll see the ArgoCD applications screen. 221  222 4. Navigate to User Info and verify Group ID. Groups will have your group’s Object ID that you added in the `Setup permissions for Entra ID Application` step. 223  224 225 ### Log in to ArgoCD using CLI 226 227 1. Open terminal, execute the below command. 228 229 argocd login <my-argo-cd-url> --grpc-web-root-path / --sso 230 231 2. You will see the below message after entering your credentials from the browser. 232  233 3. Your terminal output will be similar as below. 234 235 WARNING: server certificate had error: x509: certificate is valid for ingress.local, not my-argo-cd-url. Proceed insecurely (y/n)? y 236 Opening browser for authentication 237 INFO[0003] RequestedClaims: map[groups:essential:true ] 238 Performing authorization_code flow login: https://login.microsoftonline.com/XXXXXXXXXXXXX/oauth2/v2.0/authorize?access_type=offline&claims=%7B%22id_token%22%3A%7B%22groups%22%3A%7B%22essential%22%3Atrue%7D%7D%7D&client_id=XXXXXXXXXXXXX&code_challenge=XXXXXXXXXXXXX&code_challenge_method=S256&redirect_uri=http%3A%2F%2Flocalhost%3A8085%2Fauth%2Fcallback&response_type=code&scope=openid+profile+email+offline_access&state=XXXXXXXX 239 Authentication successful 240 'yourid@example.com' logged in successfully 241 Context 'my-argo-cd-url' updated 242 243 You may get an warning if you are not using a correctly signed certs. Refer to [Why Am I Getting x509: certificate signed by unknown authority When Using The CLI?](https://argo-cd.readthedocs.io/en/stable/faq/#why-am-i-getting-x509-certificate-signed-by-unknown-authority-when-using-the-cli).