This APPNAME installation and OURNAME AAI proxy integration guide complements the  end-user oriented guide on OURNAME AAI Proxy Installation (it will be moved elsewhere, e.g. a README, once it is completed). All information that is common to integration of various  OURNAME AAI proxy  has been OURNAME AAI Proxy Installation Document/README Outline  followed by as set of app/SP-specific guides based on the APPNAME usage with OURNAME AAI Proxy template. They should not overlap.

This text details the process of configuring the APPNAME application to function with the OURNAME AAI proxy. It

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 OURNAME AAI proxy to conceal IDP(s) and potentially centralise management for multiple applications.

About APPNAME

One paragraph summarising APPNAME from the organisational and end-user perspective.

Requirements

General Requirements

(for all apps/services)

• OURNAME proxy is set up and connected to one or several IdPs.
• SAML or OIDC configuration parameters for SPs or RPs are available.
• APPNAME is registered as an SP or RP with the proxy (!!this is most likely the subject of the OURNAME guide ).

Application-specific Requirements

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.

Preparation

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.

Deployment

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:

1. Set up Service Provider (SP) metadata.
2. Exchange metadata with AAI proxy.
3. Configure SAML assertions and bindings.

Configuration with OIDC:

1. Register SP with AAI proxy.
2. Exchange client credentials.
3. Configure OIDC scopes and claims.

Testing and Troubleshooting

Conduct integration and interoperability testing with OURNAME AAI Proxy.

Verify login functionality as end-user.

Common integration issues and solutions, e.g.:

• Testing OURNAME AAI Proxy.
• Testing IDP(s).
• Common issues and workarounds.
• Debugging tools and logs.

Best Practices

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?

Support and Contacts

If any.

Contact information for technical support.

Communication channels for issue resolution.

Contributions

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.

Background Info

Possibly remove thus in in the final template and services/apps docs

Examples for Perun ProxyIdP

• Perun ProxyIdP Git repository: https://gitlab.ics.muni.cz/perun/perun-proxyidp/sp-docs
• SP documentation, generic version (raw placeholders in the text): https://perun.gitlab-pages.ics.muni.cz/perun-proxyidp/sp-docs/
• Example of ready documentation (placeholders replaced with actual values for Masaryk University): https://perun.gitlab-pages.ics.muni.cz/perun-proxyidp/sp-docs/mu/

Customising this guide for a specific OURNAME AAI proxy instance

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' {} +