diff --git a/modules/API/pages/gsql-endpoints.adoc b/modules/API/pages/gsql-endpoints.adoc index a6bbf0e8..cac789c2 100644 --- a/modules/API/pages/gsql-endpoints.adoc +++ b/modules/API/pages/gsql-endpoints.adoc @@ -5137,6 +5137,173 @@ Sample Response:: ''' +=== Create a proxy user + +`POST /gsql/v1/proxyusers` + +Create a proxy user for SSO authentication. +Proxy users do not have local passwords and cannot authenticate using username/password. + +==== Required privilege +`WRITE_USER` + +==== Parameters +None + +==== Request body +[cols="1,1,3",options="header"] +|=== +|Field |Required |Description +|username |Yes |Proxy user name. Must match the SSO identity. +|auth_methods |No |Allowed SSO authentication methods (`KERBEROS`, `OIDC`, `SAML`). If omitted, all enabled SSO methods are allowed. +|roles |No |Roles to grant to the proxy user after creation. +|=== + +==== Example +[,tabs] +==== +Sample Request:: ++ +-- +[source,bash] +---- +curl -u tigergraph:tigergraph \ +-X POST "http://localhost:14240/gsql/v1/proxyusers" \ +-H "Content-Type: application/json" \ +-d '{ + "username": "test_user", + "auth_methods": ["OIDC"], + "roles": ["role1"] +}' +---- +-- +Sample Response:: ++ +-- +[source.wrap,console] +---- +{ + "error": false, + "message": "Successfully created proxy user test_user" +} +---- +-- +==== + +=== Delete a proxy user + +`DELETE /gsql/v1/proxyusers/{username}` + +Delete an existing proxy user. + +==== Required privilege +`WRITE_USER` + +==== Example +[,tabs] +==== +Sample Request:: ++ +-- +[source,bash] +---- +curl -u tigergraph:tigergraph \ +-X DELETE "http://localhost:14240/gsql/v1/proxyusers/test_user" +---- +-- +Sample Response:: ++ +-- +[source.wrap,console] +---- +{ + "error": false, + "message": "Successfully deleted proxy user test_user" +} +---- +-- +==== + +=== Retrieve proxy users + +`GET /gsql/v1/proxyusers` + +Retrieve all proxy users. + +==== Required privilege +`READ_USER` + +==== Example +[,tabs] +==== +Sample Request:: ++ +-- +[source,bash] +---- +curl -u tigergraph:tigergraph \ +-X GET "http://localhost:14240/gsql/v1/proxyusers" +---- +-- +Sample Response:: ++ +-- +[source.wrap,console] +---- +{ + "error": false, + "users": [ + { + "name": "test_user", + "roles": ["role1"], + "authMethods": ["OIDC"], + "groups": ["group1"] + } + ] +} +---- +-- +==== + +=== Retrieve a single proxy user + +`GET /gsql/v1/proxyusers/{username}` + +Retrieve details of a specific proxy user. + +==== Required privilege +`READ_USER` (unless requesting the current user) + +==== Example +[,tabs] +==== +Sample Request:: ++ +-- +[source,bash] +---- +curl -u tigergraph:tigergraph \ +-X GET "http://localhost:14240/gsql/v1/proxyusers/test_user" +---- +-- +Sample Response:: ++ +-- +[source.wrap,console] +---- +{ + "error": false, + "name": "test_user", + "roles": ["role1"], + "authMethods": ["OIDC"], + "groups": ["group1"], + "disabled": false, + "lastSuccessLogin": "Wed Nov 12 17:01:30 PST 2025" +} +---- +-- +==== + === retrieve users using gsql format `GET /gsql/v1/users` diff --git a/modules/reference/pages/configuration-parameters.adoc b/modules/reference/pages/configuration-parameters.adoc index d18ccbd9..19105690 100644 --- a/modules/reference/pages/configuration-parameters.adoc +++ b/modules/reference/pages/configuration-parameters.adoc @@ -1230,6 +1230,12 @@ used when returning a message. `POST` (default) sends the message content using an HTML form. `Redirect sends the message content in HTTP parameters. |`+POST+` + +|Security.SSO.EnableAutomaticCreation +|Controls whether proxy users are created automatically during first SSO login. +When set to `false`, the proxy user must already exist or login will fail. +|`true` + |=== == System diff --git a/modules/user-access/pages/sso-with-saml.adoc b/modules/user-access/pages/sso-with-saml.adoc index 01af1efe..5d701966 100644 --- a/modules/user-access/pages/sso-with-saml.adoc +++ b/modules/user-access/pages/sso-with-saml.adoc @@ -7,6 +7,9 @@ Single sign-on (SSO) enables you to use your organization's identity provider (IDP) to authenticate users to access TigerGraph GraphStudio and Admin Portal UI. We also have instructions for xref:user-access:sso-with-oidc.adoc[SSO with OIDC]. +When users authenticate through SSO, TigerGraph represents them as *proxy users*. +Proxy users do not have local passwords and can authenticate only through supported SSO methods. + We have verified the following IDPs that support SAML 2.0 protocol: * https://www.okta.com/[Okta.com] @@ -35,6 +38,36 @@ WARNING: During the SSO authentication process, TigerGraph sends a response with If you use any middleware such as an Nginx load balancer between TigerGraph and your IDP, make sure that your middleware is able to handle the size of the responses. For example, if using Nginx, make sure proxy buffering is turned on. +== Proxy users and SSO login behavior + +When a user logs in through SAML-based SSO, TigerGraph authenticates the user as a *proxy user*. + +A proxy user: + +* Does not have a local password +* Cannot log in using a username and password +* Can authenticate only through SSO +* Receives privileges from: +** Roles directly granted to the proxy user +** Roles inherited from proxy groups matched by IDP attributes + +=== Automatic proxy user creation + +By default, TigerGraph automatically creates a proxy user when an SSO user logs in for the first time. + +This behavior is controlled by the configuration parameter: + +`Security.SSO.EnableAutomaticCreation` + +* `true` (default): +Proxy users are created automatically during the first SSO login. + +* `false`: +Proxy users must already exist. +If a proxy user does not exist, login fails with the following error: + +`Automatic creation of proxy user is disabled.` + :sectnums: == Configure Identity Provider :sectnums!: @@ -371,8 +404,11 @@ used when returning a message. == Create user groups with proxy rules to authorize single sign-on users -In order to authorize single sign-on users, you need create user groups with proxy rules and grant roles on graphs for the user groups. -Proxy rules assign users who log in through SSO into proxy groups based on the attributes of the user from the identity provider's response. +In order to authorize single sign-on users, you need to create user groups with proxy rules and grant roles on graphs for those groups. +Proxy rules assign users who log in through SSO to proxy groups based on attributes returned by the identity provider. + +Starting from 4.3.0, proxy users can be created and managed explicitly. +However, proxy user group membership is still determined dynamically during SSO login based on proxy rules and identity provider (IDP) attributes. === Required privilege @@ -426,8 +462,8 @@ As of 3.10.1, the match strategy has been extended to allow matches via regular The original match strategy has not changed. ==== -For a regular expression match users need to add a prefix `regex:` -a space after the `:` is allowed. (Ex. `regex:nameid=abc, regex: nameid=abc`) +For a regular expression match, users need to add the prefix `regex:`. +A space after the `:` is allowed (for example, `regex:nameid=abc`, `regex: nameid=abc`). [NOTE] ==== @@ -515,8 +551,7 @@ Below are a few common SSO errors and how to resolve them. === "Login failed. Please contact system admin." -* If your single sign-on fails with the above error message, it usually means the configuration are inconsistent between TigerGraph and your identity provider. - +* If your single sign-on fails with the above error message, it usually means the configuration is inconsistent between TigerGraph and your identity provider. You can check your GSQL log to investigate. First, find your GSQL log file with the following: @@ -538,4 +573,4 @@ Focus on the latest errors. Usually the text is self-descriptive. Follow the error message and try to fix TigerGraph or your identity provider's configuration. -If the problem persists or if you encounter any errors that are not clear, please https://tigergraph.zendesk.com/hc/en-us/[open a support ticket]. +If the problem persists or if you encounter any errors that are not clear, please https://tigergraph.zendesk.com/hc/en-us/[open a support ticket]. \ No newline at end of file diff --git a/modules/user-access/pages/user-management.adoc b/modules/user-access/pages/user-management.adoc index 2106a52a..4b6170ef 100644 --- a/modules/user-access/pages/user-management.adoc +++ b/modules/user-access/pages/user-management.adoc @@ -141,6 +141,60 @@ For more information, see xref:security:login-protection.adoc[] If the user running the command has the `READ_USER` privilege, information on all users is displayed. Otherwise, only the current user's information is displayed. +== Show proxy users + +Proxy users represent users authenticated through Single Sign-On (SSO). +They do not have local passwords and authenticate only through SSO. + +Use the `SHOW PROXY USER` command to view proxy user metadata. + +=== Syntax + +[source,gsql] +---- +SHOW PROXY USER (, )* +---- + +=== Required privilege +`READ_USER` (unless showing the current user) + +=== Example + +[source,gsql] +---- +GSQL > SHOW PROXY USER Alice +---- + +[source,text] +---- +Users: + - Name: Alice + - Global Roles: role1 + - Groups: group1 + - AllowedAuthMethod: SAML + - Disabled: false + - LastSuccessLogin: Wed Nov 12 17:01:30 PST 2025 + - FailedAttempts: 0 +---- + +[NOTE] +==== +Proxy group membership is determined during SSO login based on identity provider attributes. +Group information may not be available until the proxy user has logged in successfully. +==== + +== View users and login activity + +The `SHOW USER` command displays both local users and proxy users. + +[source,gsql] +---- +SHOW USER +---- + +If the current user has `READ_USER`, information for all users (local and proxy) is displayed. +Otherwise, only the current user is shown. + == View privileges of a user or proxy group Users with the `READ_USER` privilege in a scope can view the RBAC privileges of users or proxy groups within that scope.