ags authentication-provider

The ags authentication-provider command manages the records that define how the identity of the user will be verified: a bind in the directory, RADIUS, OAuth2/OIDC, SAML, an HTTP request, a web form or TR7's own local database. Its panel equivalent is the Authentication Providers screen.

A provider is the method of the authentication; the server to be connected to is a separate record and is defined with ags authentication-server.

Command Summary

TR7 WEB-CLI · ags authentication-provider

admin@TR7LBWAF01> ags authentication-provider list # list all of them

admin@TR7LBWAF01> ags authentication-provider show <id> # show one

admin@TR7LBWAF01> ags authentication-provider add type <type> name <name> … # new record

admin@TR7LBWAF01> ags authentication-provider update id <id> … # change

admin@TR7LBWAF01> ags authentication-provider delete <id> # delete

admin@TR7LBWAF01>  

Writing Order

The first field written is type

In this command no field appears until the type is selected — not even the name of the record. When add is written and Tab is pressed, only type comes up in the list; name is asked for only after the type is written. If name is written without the type being selected, a Command not found: name error is received.

Step 1 Select the type

ags authentication-provider add type ldap

The moment the type is written the command takes its shape according to that type: only the fields of that type are asked for, the others never appear. To see the values, Tab is used in place of the type.

Step 2 Write the name

name corporate-login

The name is the label under which the record will appear in the list and in the other commands.

Step 3 Write the fields of the type in order

The fields listed in the tables below are all required. They are asked for without a prefix and one by one: without one being written the next is not listed, and until all of them are completed the command does not run.

Step 4 Add the optional fields

Everything that remains is written with the -- prefix and, if it is not given, stays at its default value. In this command the type is a discriminator: even if there is a field starting with -- on the line, the type-specific required fields stay prefixless, and until all of them are completed no field starting with -- is accepted. Tab shows the next field at every step.

Seeing the next field

Tab completes what can be written at the point reached; on the fields that point to another record, such as authServerId, databaseId, portalGateway, it lists the existing records by their names. When a ? is written at the end of the line and Enter is pressed, the same list comes together with its descriptions.

The Provider Types

The type field takes nine values. After the type is selected, first name and then the fields below are asked for:

type	The verification path	The required fields asked for after name
ldap	Search and bind in the directory	authServerId ldapAuthMethod ldapDefaultDomain ldapUsername ldapPassword (+ three fields according to the method)
localDb	The local database on TR7	databaseId localDbUsername localDbPassword
radius	PAP/CHAP on the RADIUS server	authServerId radiusUsername radiusPassword
oauth2	Redirection to the authorization page, the user information with a token	oauth2ClientId (+ three endpoint addresses on a custom provider)
oidc	The OAuth2 flow, the identity from a signed ID token	oauth2ClientId (+ three endpoint addresses on a custom provider)
saml	Redirection to the identity provider, a signed SAML response	samlIdpSsoUrl samlIdpCertificate samlEntityId samlAssertionConsumerServiceUrl
http	Sending the information to an HTTP service	authServerId httpMethod httpPath
webForm	Submission to the login form of an existing application	webFormLoginUrl
portal	Taking the identity from another AGS in portal mode	portalGateway

The Field Order and the Example Command Type by Type

The fields listed in the tables below are all required: the CLI asks for them in the given order, one by one, and without one being written it does not show the next field. If the command is run before these fields are completed, it returns an error. The rows marked Conditionally required are asked for only when the selection written next to them is made. Every field outside these lists is optional and is written with the -- prefix.

ldap

Order	Field	Status	Value
1	type	Required	ldap
2	name	Required	The name of the record
3	authServerId	Required	The LDAP server record to be connected to (it is selected with Tab)
4	ldapAuthMethod	Required	search-bind (default) or direct-bind
5	ldapDefaultDomain	Required	The domain name to be added if there is no domain name in the username
6	ldapUsername · ldapPassword	Required	The username and password expression to be sent to the directory
7	ldapServiceAccountDN · ldapServiceAccountPassword · ldapSearchBaseDN	Conditionally required	Only in the search-bind method

If direct-bind is selected, in place of the last three fields either ldapUserContainer or ldapCustomBindPattern is asked for, according to the bind template.

TR7 WEB-CLI · the ldap provider (search and bind)

admin@TR7LBWAF01> ags authentication-provider add type ldap name corporate-login \

authServerId <server> ldapAuthMethod search-bind ldapDefaultDomain kurum.local \

ldapUsername "%AGS_USER_INPUT(username)" ldapPassword "%AGS_USER_INPUT(password)" \

ldapServiceAccountDN "CN=svc,OU=Servis,DC=kurum,DC=local" ldapServiceAccountPassword <password> \

ldapSearchBaseDN "DC=kurum,DC=local"

admin@TR7LBWAF01>  

If the group information will be pulled as well, the group search is enabled with a separate update command: ags authentication-provider update id <id> --ldapEnableGroupSearch true. When it is enabled, the group search base and group filter fields can be written too.

The optional fields that can be written in the ldap type

Field	What it does	What is written after it
--ldapAttributes.N	Determines which additional attributes will be read from the directory	The attribute name; each one is written with its own index
--ldapBindRestrictionFilter	Filters the users that will be allowed to bind	An LDAP filter expression, for example (memberOf=CN=VPN Users,DC=kurum,DC=local)
--ldapEnableGroupSearch	Enables the group information of the user to be pulled as well	true · false (default false); when it is enabled the two fields below are asked for
--ldapGroupSearchBase	Determines the directory branch at which the group search will start	A DN, for example OU=Gruplar,DC=kurum,DC=local; it opens when --ldapEnableGroupSearch true
--ldapGroupFilter	Determines the filter that will be used in the group search	An LDAP filter expression; it opens when --ldapEnableGroupSearch true
--ldapSearchFilterType	Selects whether the ready filter or a custom filter will be used in the user search	auto (default) · custom; it opens only when ldapAuthMethod search-bind
--ldapCustomSearchFilter	Writes the custom user search filter	An LDAP filter expression; it opens when --ldapSearchFilterType custom
--ldapBindTemplate	Selects in which form the username will be sent in the direct bind	upn (user@domain) · netbios (domain\user) · uid · cn · custom (default upn); it opens only when ldapAuthMethod direct-bind
--ldapUserContainer	Determines the container in which the users are located in the direct bind	A DN; it opens when the uid or cn template is selected
--ldapCustomBindPattern	Writes the custom bind pattern that will be used in the direct bind	The pattern expression; it opens when --ldapBindTemplate custom

localDb

Order	Field	Status	Value
1	type	Required	localDb
2	name	Required	The name of the record
3	databaseId	Required	The local database record in which the users are located
4	localDbUsername · localDbPassword	Required	The username and password expression to be verified

TR7 WEB-CLI · the local database provider

admin@TR7LBWAF01> ags authentication-provider add type localDb name local-login \

databaseId <database> localDbUsername "%AGS_USER_INPUT(username)" localDbPassword "%AGS_USER_INPUT(password)"

admin@TR7LBWAF01>  

radius

Order	Field	Status	Value
1	type	Required	radius
2	name	Required	The name of the record
3	authServerId	Required	A server record with the RADIUS protocol
4	radiusUsername · radiusPassword	Required	The username and password expression to be sent to the server

The verification form is optional: with --radiusAuthType either pap (default) or chap is selected.

TR7 WEB-CLI · the radius provider

admin@TR7LBWAF01> ags authentication-provider add type radius name radius-login \

authServerId <server> radiusUsername "%AGS_USER_INPUT(username)" radiusPassword "%AGS_USER_INPUT(password)"

admin@TR7LBWAF01>  

The optional fields that can be written in the radius type

Field	What it does	What is written after it
--radiusAuthType	Selects the RADIUS verification method	pap (default) · chap
--radiusAttributes.N.name · --radiusAttributes.N.value	Adds a RADIUS attribute to the request	The attribute name and value; each pair with its own index

oauth2 and oidc

The two types share the same fields; oidc additionally reads the identity from a signed ID token.

Order	Field	Status	Value
1	type	Required	oauth2 or oidc
2	name	Required	The name of the record
3	oauth2ClientId	Required	The client id received from the provider
4	oauth2AuthorizationUrl · oauth2TokenUrl · oauth2UserInfoUrl	Conditionally required	The three endpoint addresses; they are asked for only when the provider is custom (if a selection is made from the ready catalog they are not asked)

A ready provider is selected after the add command

If the provider is not specified it is taken as custom (custom) and the three endpoint addresses are asked for. In the add command the CLI asks for these addresses in order before the --oauth2Provider field can be written; the provider field is accepted only after the required fields are completed. If a provider from the ready catalog will be used, it is selected after the record is created, with update id <id> --oauth2Provider <provider>; in the update the address fields are not required. When a ready provider is selected the addresses come by themselves. The catalog: edevlet, google, microsoft, github, githubEnterprise, gitlab, keycloak, okta, auth0, apple, x, linkedin, facebook, yandex. If apple is selected, the appleTeamId, appleKeyId and applePrivateKey fields are asked for.

The frequently used optional fields: --oauth2ClientSecret, --oauth2Scope, --oauth2RedirectUri, --namespace (the route table the request will go out from), --oauth2Tenant (for Microsoft, Keycloak, Okta, Auth0, GitLab, GitHub Enterprise), --oauth2ProviderLogout. Only in the oidc type: --oidcJwksUri.

TR7 WEB-CLI · a custom provider and a ready provider

# the custom provider: three endpoints are asked for

admin@TR7LBWAF01> ags authentication-provider add type oidc name custom-oidc \

oauth2ClientId <client-id> \

oauth2AuthorizationUrl https://idp.kurum.local/authorize \

oauth2TokenUrl https://idp.kurum.local/token \

oauth2UserInfoUrl https://idp.kurum.local/userinfo

# Google from the ready catalog: change the provider on the existing record

admin@TR7LBWAF01> ags authentication-provider update id <id> \

--oauth2Provider google --oauth2ClientId <client-id> --oauth2ClientSecret <client-secret>

admin@TR7LBWAF01>  

The optional fields that can be written in the oauth2 and oidc types

Field	What it does	What is written after it
--namespace	Selects over which route table the provider will be reached	The route table (default 1)
--oauth2Provider	Makes a selection from the ready provider catalog; the selection determines the endpoint addresses and the additional fields	custom (default) · edevlet · google · microsoft · github · apple · githubEnterprise · gitlab · keycloak · okta · auth0 · x · linkedin · facebook · yandex
--oauth2ClientSecret	Carries the client secret received from the provider	The secret key given by the provider
--oauth2Scope	Determines which permissions will be requested from the provider	A space-separated scope list, for example "openid profile email"
--oauth2RedirectUri	Determines the address to which the provider will send the user back	The return address that is defined on the provider side as well
--oauth2LogoutUrl	Determines the address to be gone to on the provider at logout	The logout address of the provider
--oauth2RevocationUrl	Determines the provider address for the token revocation	The revocation address of the provider
--oauth2RevokeOnLogout	Enables the tokens to be revoked while the session is being closed	true · false (default false)
--oauth2ProviderLogout	Enables logging out from the provider as well while the session is being closed	true · false (default false)
--oauth2ClientAuthMethod	Selects how the client will introduce itself to the provider	post in the request body (default) · basic in the header · none
--oauth2PkceRequired	Enables the PKCE protection	true · false (default false)
--oauth2PkceMethod	Selects the PKCE verification method	It opens while --oauth2PkceRequired true and a custom provider are selected
--oauth2UserInfoMethod	Selects with which method the user information will be requested	get (default) · post
--oauth2UserInfoParams.N.name · --oauth2UserInfoParams.N.value	Adds an additional parameter to the user information request	The parameter name and value; each pair with its own index
--oauth2Tenant	Determines the tenant or the instance address	The tenant id; it opens on providers such as Microsoft, Keycloak, Okta, Auth0, GitHub Enterprise
--oauth2HostedDomain	Limits the login to a single domain name	The domain name; it opens when --oauth2Provider google
--oauth2AccessType	Determines whether a refresh token will be received or not	It opens when --oauth2Provider google
--oauth2Prompt	Determines whether the provider will show its login screen every time or not	It opens when --oauth2Provider google
--appleTeamId · --appleKeyId · --applePrivateKey	Carries the signing information for the login with Apple	The team id, the key id and the .p8 private key; it opens when --oauth2Provider apple

Additionally in the oidc type:

Field	What it does	What is written after it
--oidcJwksUri	Determines the address of the key set at which the token signatures will be verified	The JWKS address
--oidcSkipSignatureVerification	Skips the verification of the token signature	true · false (default false)
--oidcSkipNonceValidation	Skips the nonce check	true · false (default false)

saml

Order	Field	Status	Value
1	type	Required	saml
2	name	Required	The name of the record
3	samlIdpSsoUrl	Required	The single sign-on address of the identity provider
4	samlIdpCertificate	Required	The signing certificate of the identity provider
5	samlEntityId	Required	The entity id of TR7 (of the service provider)
6	samlAssertionConsumerServiceUrl	Required	The address or the path to which the SAML response will return

Optionally the signature expectations (--samlWantAssertionsSigned, on by default; --samlWantResponseSigned, off by default), the name format (--samlNameIdFormat), the request binding method (--samlAuthnRequestBinding, default HTTP-Redirect) and the clock tolerance (--samlClockSkew.val, default 5 minutes) are set.

TR7 WEB-CLI · the saml provider

admin@TR7LBWAF01> ags authentication-provider add type saml name saml-login \

samlIdpSsoUrl https://idp.kurum.local/sso samlIdpCertificate <certificate> \

samlEntityId tr7-portal samlAssertionConsumerServiceUrl /ags/saml/acs

admin@TR7LBWAF01>  

The optional fields that can be written in the saml type

Field	What it does	What is written after it
--samlIdpEntityId	Determines the id with which the identity provider introduces itself	The IdP entity ID (issuer) value
--samlNameIdFormat	Determines in which form the user identity will come	urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified (default) · urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress · urn:oasis:names:tc:SAML:2.0:nameid-format:persistent · urn:oasis:names:tc:SAML:2.0:nameid-format:transient
--samlWantAssertionsSigned	Makes it mandatory for the incoming assertions to be signed	true (default) · false
--samlWantResponseSigned	Makes it mandatory for the incoming response to be signed	true · false (default false)
--samlClockSkew.val · --samlClockSkew.unit	Determines the tolerance for the clock difference between the two sides	The number and the unit (default 5 minutes)
--samlForceAuthn	Requires the user to authenticate again every time	true · false (default false)
--samlAuthnRequestBinding	Selects with which method the authentication request will be sent	HTTP-Redirect (default) · HTTP-POST

http

Order	Field	Status	Value
1	type	Required	http
2	name	Required	The name of the record
3	authServerId	Required	The HTTP server record the request will go to
4	httpMethod	Required	The request method (GET, POST, PUT… default POST)
5	httpPath	Required	The request path

What the success will be determined by is selected with --httpSuccessConditions.0; the default is statusCode and the default of the expected code is 200. When cookie, redirectUrl or jsonata is added to the condition, the httpExpectedCookieName, httpExpectedRedirectUrl and httpSuccessJsonataExpression fields are asked for as well, respectively. The body format is set with --httpBodyType (default json) and the timeout with --httpTimeout (default 30 seconds); the headers and the query parameters are added with indexed fields.

TR7 WEB-CLI · the http provider

# the plain form

admin@TR7LBWAF01> ags authentication-provider add type http name http-login \

authServerId <server> httpMethod POST httpPath /api/login

# even if a header is added, the type-specific required fields stay prefixless and are written first

admin@TR7LBWAF01> ags authentication-provider add type http name http-login \

authServerId <server> httpMethod POST httpPath /api/login \

--httpHeaders.0.name Content-Type --httpHeaders.0.value application/json

admin@TR7LBWAF01>  

The optional fields that can be written in the http type

Field	What it does	What is written after it
--httpQueryParams.N.name · --httpQueryParams.N.value	Adds a query parameter to the request	The parameter name and value; each pair with its own index
--httpHeaders.N.name · --httpHeaders.N.value	Adds an HTTP header to the request	The header name and value; each pair with its own index
--httpBodyType	Selects the format of the request body	none · multipartForm · urlEncodedForm · json (default) · raw
--httpBodyParams.N.name · --httpBodyParams.N.value	Adds a field to the body	The field name and value; it opens when --httpBodyType is json, multipartForm or urlEncodedForm and at least one pair is required
--httpRawBody	Writes the body as it is	The raw body text; it opens when --httpBodyType raw and becomes required
--httpTimeout	Determines how long the request will wait	Seconds between 1 and 300 (default 30)
--httpFollowRedirects	Determines whether the redirections will be followed or not	true (default) · false

The success criteria (with the http prefix):

Field	What it does	What is written after it
--httpSuccessConditions.N	Selects which criteria will be looked at for the login to be considered successful	statusCode (default) · cookie · redirectUrl · jsonata; more than one can be selected together
--httpExpectedStatusCodes.N	Determines the HTTP status codes that will be considered successful	The status code; it opens while the statusCode criterion is selected
--httpExpectedCookieName	Determines the name of the cookie expected to be present in the response	The cookie name; it opens while the cookie criterion is selected and becomes required
--httpExpectedRedirectUrl	Determines the redirection address expected in the response	The address; it opens while the redirectUrl criterion is selected and becomes required
--httpSuccessJsonataExpression	Allows the response body to be checked with a JSONata expression	The JSONata expression; it opens while the jsonata criterion is selected

webForm

Order	Field	Status	Value
1	type	Required	webForm
2	name	Required	The name of the record
3	webFormLoginUrl	Required	The login form address to which the information will be sent

The success condition works with the same logic as in the http type (--webFormSuccessConditions.0), but the default of the expected status code is 302 and 303. The fields to be sent to the form are written indexed: --webFormLoginFields.0.name, --webFormLoginFields.0.value.

TR7 WEB-CLI · the web form provider

admin@TR7LBWAF01> ags authentication-provider add type webForm name form-login \

webFormLoginUrl https://uygulama.kurum.local/login \

--webFormLoginFields.0.name user --webFormLoginFields.0.value "%AGS_USER_INPUT(username)" \

--webFormLoginFields.1.name pass --webFormLoginFields.1.value "%AGS_USER_INPUT(password)"

admin@TR7LBWAF01>  

The optional fields that can be written in the webForm type

Field	What it does	What is written after it
--namespace	Selects over which route table the form will be reached	The route table (default 1)
--webFormLoginFields.N.name · --webFormLoginFields.N.value	Writes the fields to be sent to the login form	The name and the value of the form field; the user input is carried with %AGS_USER_INPUT(...)

The success criteria (with the webForm prefix):

Field	What it does	What is written after it
--webFormSuccessConditions.N	Selects which criteria will be looked at for the login to be considered successful	statusCode (default) · cookie · redirectUrl · jsonata; more than one can be selected together
--webFormExpectedStatusCodes.N	Determines the HTTP status codes that will be considered successful	The status code; it opens while the statusCode criterion is selected
--webFormExpectedCookieName	Determines the name of the cookie expected to be present in the response	The cookie name; it opens while the cookie criterion is selected and becomes required
--webFormExpectedRedirectUrl	Determines the redirection address expected in the response	The address; it opens while the redirectUrl criterion is selected and becomes required
--webFormSuccessJsonataExpression	Allows the response body to be checked with a JSONata expression	The JSONata expression; it opens while the jsonata criterion is selected

portal

Order	Field	Status	Value
1	type	Required	portal
2	name	Required	The name of the record
3	portalGateway	Required	The gateway record in portal mode from which the identity will be taken

TR7 WEB-CLI · the portal provider

admin@TR7LBWAF01> ags authentication-provider add type portal name portal-login portalGateway <gateway>

admin@TR7LBWAF01>  

The Optional Fields Common to All the Types

The fields below can be written in all of the nine types.

Field	What it does	What is written after it
--userMapping.N.agsAttribute · --userMapping.N.sourceAttribute	Allows the user information coming from the provider to be mapped to the AGS fields	The AGS field and the attribute name at the source; each mapping with its own index
--buttonText	Determines the text of the button on the login page	The text that will appear on the button
--buttonIcon	Determines the icon of the login button	The icon name
--buttonColor	Determines the color of the login button	The color value
--lockoutBehaviour	Determines the lockout behavior on failed logins	inherit uses the gateway defaults (default) · override takes their place · extend adds on top of them · disabled does not lock out
--lockoutPolicies.N	Selects the lockout policies that will be applied	A lockout policy record; it opens when --lockoutBehaviour override or extend

Updating and Deleting

The update asks for the identity with the id field and changes only the fields that are written:

TR7 WEB-CLI · update and delete

admin@TR7LBWAF01> ags authentication-provider update id <id> --ldapEnableGroupSearch true

admin@TR7LBWAF01> ags authentication-provider update id <id> --userMapping.delete # empty the mappings

admin@TR7LBWAF01> ags authentication-provider delete <id>

admin@TR7LBWAF01>  

The type can be changed in the update as well; when it is changed, the fields of the new type have to be given too.

Things to Know

• The username and password fields are expressions. In the fields such as ldapUsername, localDbPassword, radiusUsername a fixed username is not written, but an expression that says where the value will come from. Their defaults are the values coming from the login form: "%AGS_USER_INPUT(username)" and "%AGS_USER_INPUT(password)".
• The values that contain parentheses are put in quotes. The command line counts the ( and ) signs as separators; for this reason values such as "%AGS_USER_INPUT(username)" and "(&(objectClass=group))" are written with double quotes. The values that contain a space (for example a DN) require quotes too. The address and path values can be written without quotes.
• There is no field that is asked for secretly. In this command the service account password, the client secret and the private key content are written directly on the command line; the line appears on the screen and falls into the command history. The setups that require secrecy can be done from the panel.
• If there is a -- on the line, the type-specific fields take -- too. type and name are always prefixless. The type-dependent fields, however, are written without a prefix only while there is no -- at all on the line; the moment an optional field is added to the line, all of them switch to the -- prefixed form.
• A provider does not work on its own. The created record is not used until it is bound to the flow of a gateway; the binding is done with ags gateway.