You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

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.

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

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

----

OURNAME AAI Proxy Installation Document/README

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:

  • Purpose or intent, which authors may sometimes omit as it may appear self-evident to them.
  • Scope, supported settings, requirements or constraints of the application which may not be apparent to a reader encountering the project on the intranet.
  • Installation and configuration.
  • Usage.
  • Roadmap and known issues.
  • Community contributions.
  • Acknowledgments, dependencies and used tools.
  • Software licence and licences of differently licensed components.

Keep technical documentation in a separate .md file.


Below are a few related scraps that could be of help:

About AAI Proxy

Overview of AAI Proxy (SAML/OIDC-based) What it serves for.

Features

The offered proxy supports (some ideas about what could be mentioned – check, I do not know where this is from!!!):

  • SAML2
    • HTTP-Redirect binding
    • HTTP-POST binding
    • Signed responses
    • Public URL with metadata in XML
  • OIDC
    • Well-known endpoint
    • Authorization endpoint
    • Public URL with keys in JWKS
    • Token endpoint
      • Optional basic authentication using client secret
    • Userinfo endpoint
    • Proof Key for Code Exchange (PKCE) - S256
    • Standard scopes and corresponding claims (OpenID, email, profile)
    • Refresh tokens

Setup

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).

Contributions

Background Info

Implementation notes, descriptions and documentation

Further reading

  • No labels