Package: aduneoclientfedid
aduneoclientfedidIdentity Federation Test Client by AduneoQuick viewaduneoclientfedidis used to test OpenID Connect, OAuth 2 and SAML configurations. It acts as a federation client mimicking an application.After an initial configuration, various flows are tested. The application may obtain tokens and assertions that can be validated, then used for user info, introspection and exchange.It is useful for:testing a newly installed identity providerlearning how identity federation worksunderstanding a specific featuredebugging a faulty client configuration by replicating itlearning how to code OpenID Connect, OAuth 2 or SAML 2Supported protocolsaduneoclientfedidsupports OpenID Connect, OAuth 2 and SAML.OpenID ConnectThe client is compatible with OpenID Connect Core 1.0 incorporating errata set 1 (https://openid.net/specs/openid-connect-core-1_0.html).OAuth 2The client is compatible withRFC 6749 The OAuth 2.0 Authorization Framework (https://www.rfc-editor.org/rfc/rfc6749)RFC 7662 OAuth 2.0 Token Introspection (https://www.rfc-editor.org/rfc/rfc7662)RFC 8707 Resource Indicators for OAuth 2.0 (https://www.rfc-editor.org/rfc/rfc8707)RFC 8693 OAuth 2.0 Token Exchange (https://www.rfc-editor.org/rfc/rfc8693)SAMLThe client is compatible with the essential parts of SAML V2.0 Specifications (http://saml.xml.org/saml-specifications)and its use with OAuth 2 :RFC 7522 Security Assertion Markup Language (SAML) 2.0 Profile
for OAuth 2.0 Client Authentication and Authorization Grants (https://www.rfc-editor.org/rfc/rfc7522)Installationaduneoclientfedidis a web server that is installed locally, most of the time onlocalhostand accessed with a web browser.Python must be installed on the system which will run the web server.
It is compatible with Python 3.6 and later.It has been tested on Windows and various Linux systems. On Windows, it can be executed from a command line prompt
or in a Powershell window.The simpliest way to install it is to download it from PyPI.First, it is advisable to create a virtual environment in a directory where you want to install the software.$mkdirclientfedid$cdclientfedid$python-mvenvmy-env(depending on your operating system, you might have to usepython3instead ofpython, or use a different command -virtualenv -p python3 my-envfor instance)and activate it. Depending on the system:$sourcemy-env/bin/activateor> my-env\Script\activatethen install it withpip:$pipinstalladuneoclientfedidBy default, packages needed for SAML are not installed, because they are tricky on some systems. If you want to use SAML,
install with the [saml] option:$pipinstalladuneoclientfedid[saml]You may have to manually install some Linux packages. Please refer to the xmlsec documentation (https://pypi.org/project/xmlsec)
for more information.Running aduneoclientfedidOnce the packages are successfully installed, create a root directory where the configuration and logs will be created.
This root directory can be located anywhere on the disk. The natural option is the directory where the Python
virtual environment (venv) has been created.If you want to create a new root directory:mkdir clientfedidcd clientfedidTwo directories will be created in this directory:confwhere a default configuration file is generatedlogMake sure the current user is allowed to create these items.There are several ways of launching the server:clientfedidaduneoclientfedidpython -m aduneoclientfedidIf successfull, a similar line is displayed:Fri Jan 6 18:15:52 2023 Server UP - https://localhost:443On Unix/Linux systems, non-administrative users are prevented by default to start a server on ports below 1024.HTTPS running on port 443, the server won't launch, with the following error:PermissionError: [Errno 13] Permission deniedThe easiest way out is to modify the port to a value larger than 1024, for instance 8443.To change the port, just had the-portargument. Launching the server on port 8443 becomes:clientfedid -port 8443When you use the previous command to launch the client for the first time (when theconfdirectory has not yet been created), the port is configured in the configuration file (the fileclientfedid.cnfin theconfdirectory).
Now you don't have to specify the port in the command line for the next execution.You can also change the listening interface, with the-hostargument.By default, the server only listens on thelocalhostinterface (127.0.0.1), meaning you can only reach it from the same computer
(with a web browser onhttps://localhost).
If you want to access it from another computer, you have to change the listening network interface.To listen on any interface, run the server with an empty host:clientfedid -host ""Now you can point a browser to something likehttps://mycomputer.domain.com.Once the server is running, stop it with Ctrl+C.This server is only meant to be running for the time when the tests are conducted. It is not optimized to run for a long time.
It is not optimized to run as a demon. It is definitely not secure enough.It is usually run on the tester's computer or on a computer controlled by the tester.Running from sourcesThere are situations where it is not possible to install the server with pip.It's still possible to run it from the sources.First, the following packages must be manually installed:certificharset_normalizer (at the time of writing, urllib3 is only compatible with version 2, not the newer version 3)idnaurllib3requestscffipycparsercryptographypyopenssldeprecatedwraptjwcryptoAdditionaly (for SAML):lxmlxmlsecSources are downloaded fromhttps://github.com/Aduneo/aduneoclientfedid, usually as a ZIP download through theCodebutton.Create a root directory.Create a Python virtual environment, activate it and install all necessary packages, in the order given earlier.Unzip the sources, go to the directory containing the aduneoclientfedid folder and run:python -m aduneoclientfedidTesting OpenID Connectaduneoclientfedidacts as an OpenID Connect Relaying Party (RP). It triggers user authentications, receives ID Tokens and retrieves
user information through theuserinfoendpoint.Once an ID token is obtained, if the RP is compatible, the token can be exchanged for an access token
(using OAuth 2.0 Token Exchange - RFC 8693).
This simulates a web application that authenticates users (OpenID Connect) and then connects to web services (OAuth 2).How it worksYou will needaduneoclientfedidinstalled and started, usually on the local machineaccess to the OpenID Provider (the identity server you want to test)a test user created on the OpenID Provider (along with its password or any other authentication method)bothaduneoclientfedidand the OP configured (more on that later)When all of this is done, connect with a web browser toaduneoclientfedidmain page. Usuallyhttps://localhost(it's possible to install it on a different machine, to change to port, and to deactivate HTTPS for testing purposes).The browser will probably display a warning since loading a page fromlocalhostis restricted when the connection is
encrypted. Bypass the warning, or change the configuration to switch to unencrypted or to connect to a real IP address.Once you have configured a flow with anOpenID Provider(as explained in the next part), you can click on theLoginbutton next to the name of the configuration you wish to test.A page is displayed with the parameters and options from the configuration. You have the liberty to change whatever you need to
perform your test. The changes only apply to the current session and leave configuration data as they are.The authentication flow is started when you click onSend to IdP.The browser is redirected to the IdP where authentication occurs. Then the browser is redirected back toaduneoclientfedidwith the result (success or error).A page is displayed with the ID Token and its validation parameters (if authentification was successful).You can then start a userinfo flow to retrieve information in the ID token.The userinfo request is added to the page and one again you change any value before hittingSend request.You can also restart an authentification flow, with the exact same parameters as the first one.ConfigurationA configuration represents a flow between an OP and a client. Once a configuration is defined, authentications can be started.You can define as many configurations as you want, with different OPs or with the same OP.A new configuration is created with theAdd OIDC Clientbutton. A name is required. Choose any name that speaks to you, for it has
no technical meaning. It is obviously advised that the name includes references to the OP and to what you are to test.Some parameters of the OIDC flow are configured in the OP and other inaduneoclientfedid.OpenID Provider configurationThe OP needs the minimum following information:redirect URI: theaduneoclientfedidURL where the browser is directed after the user has been authenticatedThis information is taken from theRedirect URIfield on theaduneoclientfedidconfiguration page. The default URL ishttps://localhost/client/oidc/login/callback(varies depending on configuration specifics). You can change it to suit you need. Make sure any custom URL is not used in a configuration from a different protocol
(OAuth 2 or SAML). To avoid that, it is better to add an indication about the protocol (oidc) in the URL.Beware that you must enter the same URL in the configurations of the OP andaduneoclientfedid.Some OP software automatically generate a client ID and a client secret. You need this information to configureaduneoclientfedid.
Other software require this information is manually entered.Depending on the OP, additional configuration is required, for example the definition of the allowed scopes, or the authentication methods allowed for the various endpoints.aduneoclientfedid configurationaduneoclientfedidneeds the following information:the OP endpoints: the URL where the browser is directed to authenticate the user and URLs for various OP web services (token retrieval, public keys, userinfo, etc.)client ID, identifying the client in the OPclient secret (the password associated with the client ID)the method used to authenticate the clientWhile it is possible to detail every endpoint URL, the easiest way is to give the discovery URI, also known as the well known
configuration endpoint that returns theconfiguration documentwith all necessary information.This discovery URL is the following construct: issuer URL +/.well-known/openid-configuration.Here are some examples:Azure AD:https://login.microsoftonline.com/\/v2.0/.well-known/openid-configurationOkta: https://<domain>.okta.com/.well-known/openid-configurationForgeRock AM: https://<server>/am/oauth2/<realm>/.well-known/openid-configurationKeycloak: https://<server>/realms/<realm>/.well-known/openid-configurationThe client ID and client secret are either generated by the OP or entered in the OP configuration.The authentication method describes how these credentials are transmitted:POST: in the HTTP body (widely used)Basic: in the HTTP headersSome OPs accept any authentication method while other must be precisely configured.Default parametersWhen configuring an OpenID Connect service, you also provide default values for flow parameters.Thescopesare keywords representing information that the OP should send alongside the identity after a successfull
authentication. Multiple scopes are separated by spaces.The parameter MUST containopenidper OIDC’s flow configured in the client (it distinguishes an OpenID Connect flow and an OAuth 2 flow).The OpenID Connect Specifications define several default scopes and additional ones which can be configured in the OP.The most used scopes for testing purposes are "openid email profile" :openid indicates an OpenID Connect flowemail is obviously the email addressprofile returns basing information about the user: name, given name, gender, locale, birthdate, etc.aduneoclientfedidis only compatible with thecoderesponse type, the implicit flow being deprecated since 2018.OptionsOptions describeaduneoclientfedid's behavior out of the OpenID Connect specifications.The only option indicates is HTTPS certificates must be validated.When testing a production environment, it is advised to verify certificates, to replicate the exact flows.Other environments typically have specific certificates (self-signed or signed by an internal PKI). Since certificate verification will likely fail, it's best to disable it.OpenID Connect LogoutaduneoclientfedidimplementsOpenID Connect RP-Initiated Logout 1.0, but not yet either Front-Channel or Back-Channel.Logout is initiated from the home page.Testing OAuth 2aduneoclientfedidacts both as a OAuth 2 client (a web app) and a resource server (RS, ie a web service).In a first stepaduneoclientfedidsimulates a client, triggers a user authentication and receives an access token (AT).
Then it takes the role of a resource server that would have been inkoved by the client. The RS would have received the access token and now has to validate it.The validation method depends on the nature of the access token:JWTs are validated by verifying the signature (not yet implemented byaduneoclientfedidfor ATs)opaque tokens must beintrospected(presented to the introspection endpoint for validation and user information retrieval)aduneoclientfedidperforms token exchanges (RFC 8693) to get other access tokens or ID tokens from an access token. At the time of writing very few AS have implemented this RFC.OAuth 2 flows (introspections and token exchanges) can also be initiated after a SAML authentication.How it worksYou will needaduneoclientfedidinstalled and started, usually on the local machineaccess to the Authorization Server (the identity server you want to test)a test user created on the Authorization server (along with its password or any other authentication method)bothaduneoclientfedidand the OP configured (more on that later)When all of this is done, connect with a web browser toaduneoclientfedidmain page. Usuallyhttps://localhost(it's possible to install it on a different machine, to change to port, and to deactivate HTTPS for testing purposes).The browser will probably display a warning since loading a page fromlocalhostis restricted when the connection is
encrypted. Bypass the warning, or change the configuration to switch to unencrypted or to connect to a real IP address.Once you have configured a flow with anauthorization server(as explained in the next part), you can click on theLoginbutton next to the name of the configuration you wish to test.A page is displayed with the parameters and options from the configuration. You have the liberty to change whatever you need to
perform your test. The changes only apply to the current session and leave configuration data as they are.The authentication flow is started when you click onSend to IdP.The browser is redirected to the AS where authentication occurs. Then the browser is redirected back toaduneoclientfedidwith the result (success or error).A page is displayed with the Access Token.Then, you can start an introspection flow or a token exchange flow.ConfigurationA configuration represents a flow between an Authorization Server and a client. Once a configuration is defined, authorizations can be started.You can define as many configurations as you want, with different ASs or with the same AS.A new configuration is created with theAdd OAuth Clientbutton. A name is required. Choose any name that speaks to you, for it has
no technical meaning. It is obviously advised that the name includes references to the OP and to what you are to test.Some parameters of the OAuth 2 flow are configured in the OP and other in aduneoclientfedid.Authorization Server configurationThe AS needs the minimum following information:redirect URI: theaduneoclientfedidURL where the browser is directed after the user has been authenticatedThis information is taken from theRedirect URIfield on theaduneoclientfedidconfiguration page. The default URL ishttps://localhost/client/oidc/login/callback(varies depending on configuration specifics). You can change it to suit you need. Make sure any custom URL is not used in a configuration from a different protocol
(OIDC or SAML). To avoid that, it is better to add an indication about the protocol (oidc) in the URL.Beware that you must enter the same URL in the configurations of the OP andaduneoclientfedid.Some AS software automatically generate a client ID and a client secret. You need this information to configureaduneoclientfedid. Other software require this information is manually entered.Depending on the AS, additional configuration is required, for example the definition of the allowed scopes, or the authentication methods allowed for the various endpoints.If introspection is used for validating the AT, you need to create a configuration foraduneoclientfedidacting as a resource server. All is needed is a login and a secret.
Each authorization server software has its own configuration waysome have dedicated objects to represent a RSothers treat RS as clients with minimal configuration
Refer to the software documentation to determine how to proceed.aduneoclientfedid configurationTheaduneoclientfedidconfiguration page is split in 2 sections:"Token request by the client" is the configuration when it acts as a client"Token validation by the API (resource server)" when it acts as a resource serverTo obtain an Access Token, the following information is needed:the AS endpoints: URL where the browser is directed to authenticate the user and URLs for various AS web services (token retrieval, introspection, etc.)client ID, identifying the client in the ASclient secret (the password associated with the client ID)the method used to authenticate the clientOAuth does not have a discovery URI mechanism like OpenID Connect, where the client can retrieve all endpoints (and additional parameters).
Normally, each individual endpoint must be provided.But some AS software publish a discovery URI, which can be the same as OpenID Connect, or different. If it's different, make sure to enter the correct URI. Otherwise
you might have an unpredictable behavior.This is the case with Okta :https://<domain>.okta.com/.well-known/oauth-authorization-serverForgeRock AM has the same discovery URI for OpenID Connect and OAuth 2.The client ID and client secret are either generated by the AS or entered in the AS configuration.The authentication method describes how these credentials are transmitted:POST: in the HTTP body (widely used)Basic: in the HTTP headersSome Authorization Servers accept any authentication method while other must be precisely configured.If tokens are validated by introspection, you can configure how to perform it:introspection endpoint (if not retrieved through the discovery URI)resource server client ID: the login used by the web service that has received the Access Tokenresource server secret: the corresponding secret (aduneoclientfedidis only compatible with a password at the moment)Default parametersWhen configuring an OAuth 2 service, you also provide default values for flow parameters.Thescopesare keywords representing the type of access that is requested. They are entirely dependent on your own installation. They usually represent access types (read, write, create, delete, etc.).Theresourceparameter is defined by RFC 8707 but not implemented by many AS. Check compatibility before using it.aduneoclientfedidis only compatible with thecoderesponse type, the implicit flow being deprecated since 2018.OptionsOptions describeaduneoclientfedid's behavior outside of the OAuth RFCs.The only option indicates if HTTPS certificates must be validated.When testing a production environment, it is advised to verify certificates, to replicate the exact flows.Other environments typically have specific certificates (self-signed or signed by an internal PKI). Since certificate verification will likely fail, it's best to disable it.Access Token IntrospectionAfter an access token has been obtained, it can be introspected.After clicking on the "Introspect AT" button, a form is displayed in two parts:first the parameters defined by RFC 7662 (token and token type hint)then the request as it is going to be sent to the authorization server: endpoint, data, authentication parametersAny change in the first part is reflected on the second (but not the other war around).During tests, you'll probably have to enter the same information many times (credentials for instance). To help you with that, you can use the internal clipboard.
It keeps all inputs that are entered so that you just have to select it when it's needed again.
The clipboard is opened when clicking the icon on the right of each form field.
By default, passwords are not stored in the clipboard, but a configuration parameter enables this feature.Refreshing Access TokensIf a refresh token (RT) was retrieved during OAuth flow, it can be used to get a new access token.As with introspection, a two-part form is displayed:top form: parameters defined by RFC 6749 (section 6)bottom form: the request as it will be sent to the authorization serverToken ExchangeRFC 8693 defines a way to obtain a new token (ID or access) from an existing valid token (ID or access).Few authorization servers have implemented it, so check it's available.Testing SAML 2aduneoclientfedidis a SAML 2 Service Provider (SP). It simulates an application authenticating to an Identity Provider (IdP).SAML authentication is only available when thexmlsecPython module is installed. Refer to this page for instruction on how to install it:https://pypi.org/project/xmlsec/.
Sometimes it's easy (Windows) sometimes it requires some skills (Ubuntu).After a successful authentication an OAuth 2 Access Token can be obtained when the IdP is compatible with RFC 7522
(Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants).How it worksYou will needaduneoclientfedidinstalled and started, usually on the local machineaccess to the Identity Provider (the identity server you want to test)a test user created on the IdP (along with its password or any other authentication method)bothaduneoclientfedidand the IdP correctly configured (more on that later)When all of this is done, connect with a web browser toaduneoclientfedidmain page. Usuallyhttps://localhost(it's possible to install it on a different machine, to change to port, and to deactivate HTTPS for testing purposes).The browser will probably display a warning since loading a page fromlocalhostis restricted when the connection is
encrypted. Bypass the warning, or change the configuration to switch to unencrypted or to connect to a real IP address.Once you configured a flow in the client as explained in the next part, you can click on theLoginbutton next to the name of the configuration you wish to test.A page is displayed with the default configuration and the default options. You have the liberty to change whatever you need to
perform your test.The authentication flow is started when you click onSend to IdP.The browser is redirected to the IdP where authentication occurs. Then the browser is redirected toaduneoclientfedid.A page is displayed with the SAML assertion and its validation parameters.You can then retrieve an access token if needed (and if the IdP is RFC 7522 compliant).ConfigurationA configuration represents a flow between an Identity Provider and a client. Once a configuration is defined, authentications can be started.You can define as many configurations as you want, with different IdPs or with the same IdP.A new configuration is created with theAdd SAML SPbutton. A name is required. Choose any name that speaks to you, for it has
no technical meaning. It is obviously advised that the name includes references to the OP and to what you are to test.A SAML configuration is an exchange of metadata files :the SP generates an XML file that is uploaded to the IdPthe IdP generates an XML file that is uploaded to the SPWhile this is the easy way to proceed, it is still possible to enter each parameter individually.Having gathered information from the IdP, you configureaduneoclientfedideither by uploading the metadata file, which results in the parameter fields being automatically populatedor by manually entering it: entity ID, SSO URL and certificate (optionally Single Logout URL)
The certificate must be in PEM format, with or without a header and a footer.aduneoclientfedidgenerates an XML metadata file based on the information provided in the form:SP Entity ID: references the SP. It must be a URI, it is recommended it is a URLSP Assertion Consumer Service (ACS) URL: callback URL toaduneoclientfedidafter authentication. Default ishttps://localhost/client/saml/login/acs, but you can change it (as long as it stays in the same domain).keys and certificate: this information is used to sign the requests. You can either use the default key or provide your own
(in case you want to replicate an exact real world behavior). Communicate the certificate butNOT the private key.NameID policy: expected user identifier field returned in the SAML assertionAuthentication binding: method used to send an authentication requestLogout binding (optional): method used to send a logout requestThose values are communicated to the IdP either manually or via a metadata file (downloaded through theDownload SP metadatabutton)There obviously needs to be a coherence between the configurations of the SP and the IdP.Many problems arise because of incompatible NameID policies. NameID is the field with the user's identity. SAML defines different formats and different values.
The easiest format to configure would be the email (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress), but it is not always the best choice for an identifier
(actually, it's a pretty terrible choice in most cases). A better option is an uid present in the identity repository of the organization, which has to be conveyed
in the unspecified format (urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified). It often requires a specific configuration on the IdP part.SAML Logoutaduneoclientfedidimplements Single Logout, with the POST or Redirect bindings.Logout is initiated from the home page.General configurationSome configuration parameters affecting the server behaviour are modified in the configuration file, using your
favorite editor. There is no web console now for these parameters.The configuration file is named clientfedid.cnf and is in the conf directory that has been created in the current folder
(the one from which the python command has been issued).It's a JSON file, so be careful of trailing commas. As a reminder, the following syntax is not permitted by JSON:{"param1": "value1","param2": "this will result in an error",}(remove the last comma to make it JSON compliant)There are 6 main sections in the configuration file:meta: information about the configuration file itself. It only contains the name of the file containing the key used to encrypt
passwordsserver: HTTP server parameters (port, SSL, etc.)preferencesoidc_clients, oauth_clients, saml_clients: these parts detail the various clients and configurations in the applicationAny manual change in thre configuration file requires the server to be restarted (Ctrl-C then clientfedid/aduneoclientfedid/python -m aduneoclientfedid).meta/key: encryption key file nameAll parameters with a name ending with an exclamation point (!) are automatically encrypted (client secrets), using a symmetric key.A key is automatically generated at first launch and store in a file named clientfedid.key.It is a good practice to protect this file.server/hostIdentifies the network card used by the HTTP server.Using the default localhost makes sure no other machine is (easily...) able to access it.An empty value ("") opens it to anyone (depending on your local firewall settings).It can be a name or an IP address.server/portListening port for the HTTP server.Default is 443. It might not work on Unix/Linux systems. The easiest fix is to choose a port number greater than 1024 (8443 is a good
candidate).server/sslActivates HTTPS. Possible values areonandoff.Since most of the security of OpenID Connect/OAuth 2 relies on HTTPS, it is advisable to leave the default (on).But you may have to turn it off for testing purposes.server/ssl_key_file and server/ssl_cert_fileWhen SSL is activated, these parameters contains the file withthe SSL private key (ssl_key_file), PEM formatthe associated certificate (ssl_cert_file), PEM formatIf those files are not referenced in the configuration file (which is the default), aduneoclientfedid will automatically create
a key and certificate. Those items are deleted after the server is stopped.The certificate is self-signed, with server/host as the subject (the FQDN of the machine if server/host is empty).preferences/logging/handlerList of logging handlers:console: displays logs in the window used to launch the serverfile: adds logs in a file in a directory (logs) created alongsideconfdirectory.webconsole: displays logs in a browser window that can be opened by "console" button on the upper right side of the page, or
automatically when an authentication flow is startedBy default, all handlers are activated.preferences/open_webconsole:onif the browser window displaying logs is automatically opened every time an authentication flow is started (default).preferences/clipboard/encrypt_clipboardThe clipboard stores all texts typed in application forms, to be easily used multiple times without having to enter them each time.Its content is stored in theconfdirectory.Ifencrypt_clipboardison, the file is encrypted usingclientfedid.keyas a key. This is the default.Otherwise, its content is in plain text.preferences/clipboard/remember_secretsIndicates if secrets are stored in the clipboard (default isoff).