This text details the process of configuring the APPNAME application to function with the OURNAME AAI proxy. The document aims to assist service providers in setting up APPNAME and integrating it with an instance of OURNAME AAI proxy, which acts as an identity provider using SAML (or OIDC) support provided by APPNAME. The integration streamlines APPNAME setup and maintenance by leveraging the BRANDNAME AAI proxy to conceal IDP(s) and potentially centralise management for multiple applications.
One paragraph summarising APPNAME from the organisational and end-user perspective.
(for all apps/services)
Specify the earliest APPNAME version supporting this integration. Installing a SAML or OIDC plug-in for APPNAME if needed. Custom/prepared installations or images of APPNAME if any. Include any other APPNAME-specific requirements.
Set up OURNAME AAI Proxy.
Obtain necessary information for AAI proxy as an identity provider.
Get/download APPNAME.
Get/download SAML or OIDC libraries or plug-in for APPNAME if needed.
Install APPNAME.
Basic APPNAME setup if not conducted during installation.
Install/integrate SAML or OIDC libraries or plug-in for APPNAME if needed.
Provide SAML or OIDC configuration parameters into APPNAME or plug-in.
Move this to our OURNAME AAI proxy guide? Configure service/application settings with the proxy, e.g.:
Configuration with SAML:
Configuration with OIDC:
Conduct integration and interoperability testing with OURNAME AAI Proxy.
Verify login functionality as end-user.
Common integration issues and solutions, e.g.:
Security considerations if any.
Propose to inform/educate end-users and describe possible ways to do it.
Provide user instructions on how to log in to APPNAME using an IdP connected to OURNAME AAI Proxy.
Anything else?
If any.
Contact information for technical support.
Communication channels for issue resolution.
Location of this guide (best to keep in the same repository as OURNAME AAI Proxy but in a separate folder) Provide information on how to contribute to this guide and the licensing of contributions. How to contribute with similar guides for other applications and services.
Possibly remove thus in in the final template and services/apps docs
Examples for Perun ProxyIdP
On Pavel's trail: Can we customise documentation it by directly using user provided data? The magic of replacing placeholders with actual values: https://gitlab.ics.muni.cz/perun/perun-proxyidp/sp-docs/-/blob/main/.gitlab-ci.yml?ref_type=heads This documentation is meant to be customised with specific information about the Identity Provider (IdP) and then published for Service Providers to reference. Copy the files or clone the repository, replacing all placeholders mentioned in the list of placeholders. For instance, to replace %OIDC_ISSUER% with https://oidc.muni.cz/oidc/, execute:
bash
find . -type f -name "*.md" -exec sed -i 's/%OIDC_ISSUER%/https:\/\/oidc.muni.cz\/oidc\//g' {} +
This should be a separate doc, possibly the proxy's README. You can base it on https://wiki.geant.org/pages/viewpage.action?pageId=725614690#SoftwarelicenceselectionandmanagementinG%C3%89ANT-READMEFile, following this structure:
Keep technical documentation in a separate .md file.
Below are a few related scraps that could be of help:
Overview of AAI Proxy (SAML/OIDC-based) What it serves for.
The offered proxy supports (some ideas about what could be mentioned – check, I do not know where this is from!!!):
Where is available.
How to install it.
Configuration.
Connecting it to IdP(s).
Capturing SAML or OIDC configuration parameters for providing to the SPs or RPs.
Registration of SPs or RPs with the proxy.
How to check if it works (could be a separate section).
How to check if the SPs or RPs is registered (without using it).
Implementation notes, descriptions and documentation
Further reading