Authentication - Turn-key research data management repository

<!doctype html> <html lang="en" class="no-js"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width,initial-scale=1"> <link rel="canonical" href="https://inveniordm.docs.cern.ch/customize/authentication/"> <link rel="prev" href="../look-and-feel/font/"> <link rel="next" href="../emails/"> <link rel="icon" href="../../images/favicon.svg"> <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.40"> <title>Authentication - Turn-key research data management repository</title> <link rel="stylesheet" href="../../assets/stylesheets/main.8c3ca2c6.min.css"> <link rel="stylesheet" href="../../assets/stylesheets/palette.06af60db.min.css"> <link rel="stylesheet" href="../../stylesheets/extra.css"> <script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script> </head> <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="custom" data-md-color-accent="custom"> <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off"> <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off"> <label class="md-overlay" for="__drawer"></label> <div data-md-component="skip"> <a href="#authentication" class="md-skip"> Skip to content </a> </div> <div data-md-component="announce"> </div> <header class="md-header" data-md-component="header"> <nav class="md-header__inner md-grid" aria-label="Header"> <a href="../.." title="Turn-key research data management repository" class="md-header__button md-logo" aria-label="Turn-key research data management repository" data-md-component="logo"> <img src="../../images/logo-rdm.png" alt="logo"> </a> <label class="md-header__button md-icon" for="__drawer"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class="md-header__title" data-md-component="header-title"> <div class="md-header__ellipsis"> <div class="md-header__topic"> Turn-key research data management repository </div> <div class="md-header__topic" data-md-component="header-topic"> Authentication </div> </div> </div> <form class="md-header__option" data-md-component="palette"> <input class="md-option" data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme="default" data-md-color-primary="custom" data-md-color-accent="custom" aria-label="Switch to dark mode" type="radio" name="__palette" id="__palette_0"> <label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_1" hidden> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class="md-option" data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme="slate" data-md-color-primary="black" data-md-color-accent="orange" aria-label="Switch to light mode" type="radio" name="__palette" id="__palette_1"> <label class="md-header__button md-icon" title="Switch to light mode" for="__palette_0" hidden> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for="__search"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class="md-search" data-md-component="search" role="dialog"> <label class="md-search__overlay" for="__search"></label> <div class="md-search__inner" role="search"> <form class="md-search__form" name="search"> <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required> <label class="md-search__icon md-icon" for="__search"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </label> <nav class="md-search__options" aria-label="Search"> <button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg> </button> </nav> </form> <div class="md-search__output"> <div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix> <div class="md-search-result" data-md-component="search-result"> <div class="md-search-result__meta"> Initializing search </div> <ol class="md-search-result__list" role="presentation"></ol> </div> </div> </div> </div> </div> <div class="md-header__source"> <a href="https://github.com/inveniosoftware/docs-invenio-rdm" title="Go to repository" class="md-source" data-md-component="source"> <div class="md-source__icon md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81"/></svg> </div> <div class="md-source__repository"> GitHub </div> </a> </div> </nav> </header> <div class="md-container" data-md-component="container"> <nav class="md-tabs" aria-label="Tabs" data-md-component="tabs"> <div class="md-grid"> <ul class="md-tabs__list"> <li class="md-tabs__item"> <a href="../.." class="md-tabs__link"> Home </a> </li> <li class="md-tabs__item"> <a href="../../features/" class="md-tabs__link"> Features </a> </li> <li class="md-tabs__item"> <a href="../../install/" class="md-tabs__link"> Install </a> </li> <li class="md-tabs__item md-tabs__item--active"> <a href="../" class="md-tabs__link"> Customize </a> </li> <li class="md-tabs__item"> <a href="../../develop/" class="md-tabs__link"> Develop </a> </li> <li class="md-tabs__item"> <a href="../../deploy/" class="md-tabs__link"> Deploy </a> </li> <li class="md-tabs__item"> <a href="../../reference/" class="md-tabs__link"> Reference </a> </li> <li class="md-tabs__item"> <a href="../../releases/" class="md-tabs__link"> Releases </a> </li> <li class="md-tabs__item"> <a href="../../maintenance/" class="md-tabs__link"> Maintainers </a> </li> <li class="md-tabs__item"> <a href="../../contribute/" class="md-tabs__link"> Onboard & Contribute </a> </li> </ul> </div> </nav> <main class="md-main" data-md-component="main"> <div class="md-main__inner md-grid"> <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" > <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner"> <nav class="md-nav md-nav--primary md-nav--lifted" aria-label="Navigation" data-md-level="0"> <label class="md-nav__title" for="__drawer"> <a href="../.." title="Turn-key research data management repository" class="md-nav__button md-logo" aria-label="Turn-key research data management repository" data-md-component="logo"> <img src="../../images/logo-rdm.png" alt="logo"> </a> Turn-key research data management repository </label> <div class="md-nav__source"> <a href="https://github.com/inveniosoftware/docs-invenio-rdm" title="Go to repository" class="md-source" data-md-component="source"> <div class="md-source__icon md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81"/></svg> </div> <div class="md-source__repository"> GitHub </div> </a> </div> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../.." class="md-nav__link"> Home </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2" > <label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="0"> Features </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_2"> Features </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../features/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../features/ux/" class="md-nav__link"> Beautiful UX </a> </li> <li class="md-nav__item"> <a href="../../features/scalable/" class="md-nav__link"> Highly scalable </a> </li> <li class="md-nav__item"> <a href="../../features/customization/" class="md-nav__link"> Customizable </a> </li> <li class="md-nav__item"> <a href="../../features/interoperable/" class="md-nav__link"> Interoperable </a> </li> <li class="md-nav__item"> <a href="../../features/powerful/" class="md-nav__link"> Powerful </a> </li> <li class="md-nav__item"> <a href="../../features/secure/" class="md-nav__link"> Secure </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_8" > <label class="md-nav__link" for="__nav_2_8" id="__nav_2_8_label" tabindex="0"> Features walk-through </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_2_8_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_2_8"> Features walk-through </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../features/features-walk-through/" class="md-nav__link"> Features overview </a> </li> <li class="md-nav__item"> <a href="../../features/features-walk-through/banners/" class="md-nav__link"> Site banners </a> </li> <li class="md-nav__item"> <a href="../../features/features-walk-through/notifications/" class="md-nav__link"> Notifications </a> </li> <li class="md-nav__item"> <a href="../../features/features-walk-through/access_requests/" class="md-nav__link"> Access requests </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" > <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0"> Install </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_3"> Install </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../install/" class="md-nav__link"> Quick start </a> </li> <li class="md-nav__item"> <a href="../../install/requirements/" class="md-nav__link"> System requirements </a> </li> <li class="md-nav__item"> <a href="../../install/cli/" class="md-nav__link"> Install CLI </a> </li> <li class="md-nav__item"> <a href="../../install/scaffold/" class="md-nav__link"> Scaffold </a> </li> <li class="md-nav__item"> <a href="../../install/build-setup-run/" class="md-nav__link"> Build, setup & run </a> </li> <li class="md-nav__item"> <a href="../../install/configuration/" class="md-nav__link"> Configure </a> </li> <li class="md-nav__item"> <a href="../../install/run/" class="md-nav__link"> Use </a> </li> <li class="md-nav__item"> <a href="../../install/migrate/" class="md-nav__link"> Migrate </a> </li> <li class="md-nav__item"> <a href="../../install/destroy/" class="md-nav__link"> Destroy </a> </li> <li class="md-nav__item"> <a href="../../install/troubleshoot/" class="md-nav__link"> Troubleshooting </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" checked> <label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex=""> Customize </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="true"> <label class="md-nav__title" for="__nav_4"> Customize </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4_2" > <label class="md-nav__link" for="__nav_4_2" id="__nav_4_2_label" tabindex="0"> Look-and-feel </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_4_2_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_4_2"> Look-and-feel </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../look-and-feel/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../look-and-feel/logo/" class="md-nav__link"> Change logo </a> </li> <li class="md-nav__item"> <a href="../look-and-feel/templates/" class="md-nav__link"> Change templates </a> </li> <li class="md-nav__item"> <a href="../look-and-feel/theme/" class="md-nav__link"> Change theme </a> </li> <li class="md-nav__item"> <a href="../look-and-feel/font/" class="md-nav__link"> Change font </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--active"> <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc"> <label class="md-nav__link md-nav__link--active" for="__toc"> Authentication </label> <a href="./" class="md-nav__link md-nav__link--active"> Authentication </a> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#local-authentication" class="md-nav__link"> Local Authentication </a> <nav class="md-nav" aria-label="Local Authentication"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#disabling-local-authentication" class="md-nav__link"> Disabling local authentication </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#external-authentication" class="md-nav__link"> External authentication </a> <nav class="md-nav" aria-label="External authentication"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#oauth" class="md-nav__link"> OAuth </a> <nav class="md-nav" aria-label="OAuth"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#orcid" class="md-nav__link"> ORCID </a> </li> <li class="md-nav__item"> <a href="#github" class="md-nav__link"> GITHUB </a> </li> <li class="md-nav__item"> <a href="#keycloak" class="md-nav__link"> Keycloak </a> <nav class="md-nav" aria-label="Keycloak"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#configuration" class="md-nav__link"> Configuration </a> </li> <li class="md-nav__item"> <a href="#tweaking-configuration" class="md-nav__link"> Tweaking configuration </a> </li> <li class="md-nav__item"> <a href="#multiple-keycloak-authentication-providers" class="md-nav__link"> Multiple Keycloak authentication providers </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#openaire-aai" class="md-nav__link"> OpenAIRE AAI </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#login-automatic-redirection" class="md-nav__link"> Login automatic redirection </a> </li> <li class="md-nav__item"> <a href="#user-profile-update" class="md-nav__link"> User profile update </a> </li> <li class="md-nav__item"> <a href="#auto-confirm-user" class="md-nav__link"> Auto-confirm user </a> </li> <li class="md-nav__item"> <a href="#on-the-precedence-mask" class="md-nav__link"> On the precedence mask </a> </li> <li class="md-nav__item"> <a href="#defining-post-logout-url" class="md-nav__link"> Defining post logout url </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#security" class="md-nav__link"> Security </a> </li> <li class="md-nav__item"> <a href="#advanced-integrations" class="md-nav__link"> Advanced integrations </a> <nav class="md-nav" aria-label="Advanced integrations"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#custom-login-page" class="md-nav__link"> Custom login page </a> </li> <li class="md-nav__item"> <a href="#custom-user-registration-form" class="md-nav__link"> Custom user registration form </a> </li> <li class="md-nav__item"> <a href="#custom-user-info" class="md-nav__link"> Custom user info </a> </li> <li class="md-nav__item"> <a href="#new-oauth-plugins" class="md-nav__link"> New OAuth plugins </a> </li> <li class="md-nav__item"> <a href="#allowdeny-user-login" class="md-nav__link"> Allow/deny user login </a> </li> <li class="md-nav__item"> <a href="#saml-integration" class="md-nav__link"> SAML integration </a> <nav class="md-nav" aria-label="SAML integration"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#prerequisites" class="md-nav__link"> Prerequisites </a> </li> <li class="md-nav__item"> <a href="#server-information" class="md-nav__link"> Server information </a> </li> <li class="md-nav__item"> <a href="#configuration_1" class="md-nav__link"> Configuration </a> </li> <li class="md-nav__item"> <a href="#automatically-confirm-users" class="md-nav__link"> Automatically confirm users </a> <nav class="md-nav" aria-label="Automatically confirm users"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#example-configurations-element" class="md-nav__link"> Example configurations element </a> </li> <li class="md-nav__item"> <a href="#troubleshooting-saml-configuration" class="md-nav__link"> Troubleshooting SAML configuration </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#show-the-login-button" class="md-nav__link"> Show the login button </a> </li> <li class="md-nav__item"> <a href="#multiple-saml-authentication-providers" class="md-nav__link"> Multiple SAML authentication providers </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#groups" class="md-nav__link"> Groups </a> <nav class="md-nav" aria-label="Groups"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#add-groups" class="md-nav__link"> Add groups </a> </li> <li class="md-nav__item"> <a href="#assign-groups-on-login" class="md-nav__link"> Assign groups on login </a> </li> </ul> </nav> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../emails/" class="md-nav__link"> Sending emails </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4_5" > <label class="md-nav__link" for="__nav_4_5" id="__nav_4_5_label" tabindex="0"> Search </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_4_5_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_4_5"> Search </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../search/" class="md-nav__link"> Change facets/sorting </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4_6" > <label class="md-nav__link" for="__nav_4_6" id="__nav_4_6_label" tabindex="0"> Vocabularies </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_4_6_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_4_6"> Vocabularies </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../vocabularies/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../vocabularies/resource_types/" class="md-nav__link"> Resource types </a> </li> <li class="md-nav__item"> <a href="../vocabularies/affiliations/" class="md-nav__link"> Affiliations </a> </li> <li class="md-nav__item"> <a href="../vocabularies/names/" class="md-nav__link"> Names </a> </li> <li class="md-nav__item"> <a href="../vocabularies/funding/" class="md-nav__link"> Funding </a> </li> <li class="md-nav__item"> <a href="../vocabularies/subjects/" class="md-nav__link"> Subjects </a> </li> <li class="md-nav__item"> <a href="../vocabularies/users/" class="md-nav__link"> Users </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4_7" > <label class="md-nav__link" for="__nav_4_7" id="__nav_4_7_label" tabindex="0"> Metadata </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_4_7_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_4_7"> Metadata </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../metadata/optional_fields/" class="md-nav__link"> Optional metadata </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4_7_2" > <label class="md-nav__link" for="__nav_4_7_2" id="__nav_4_7_2_label" tabindex="0"> Custom fields </label> <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_4_7_2_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_4_7_2"> Custom fields </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../metadata/custom_fields/records/" class="md-nav__link"> Add fields to records </a> </li> <li class="md-nav__item"> <a href="../metadata/custom_fields/communities/" class="md-nav__link"> Add fields to communities </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../record_landing_page/" class="md-nav__link"> Record landing page </a> </li> <li class="md-nav__item"> <a href="../static_pages/" class="md-nav__link"> Static pages </a> </li> <li class="md-nav__item"> <a href="../dois/" class="md-nav__link"> DOI registration </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4_11" > <label class="md-nav__link" for="__nav_4_11" id="__nav_4_11_label" tabindex="0"> Other PIDs integrations </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_4_11_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_4_11"> Other PIDs integrations </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../other-pids/urns/" class="md-nav__link"> DNB URNs </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../s3/" class="md-nav__link"> Storage </a> </li> <li class="md-nav__item"> <a href="../upload_limits/" class="md-nav__link"> Upload Limits </a> </li> <li class="md-nav__item"> <a href="../metadata_only/" class="md-nav__link"> Metadata-only records </a> </li> <li class="md-nav__item"> <a href="../Logging/" class="md-nav__link"> Logging </a> </li> <li class="md-nav__item"> <a href="../i18n-and-l10n/" class="md-nav__link"> Internationalisation (i18n) and Localisation (l10n) </a> </li> <li class="md-nav__item"> <a href="../notifications/" class="md-nav__link"> Notifications </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" > <label class="md-nav__link" for="__nav_5" id="__nav_5_label" tabindex="0"> Develop </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_5"> Develop </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../develop/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5_2" > <label class="md-nav__link" for="__nav_5_2" id="__nav_5_2_label" tabindex="0"> Getting started </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_5_2_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_5_2"> Getting started </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../develop/getting-started/source-code/" class="md-nav__link"> Source code </a> </li> <li class="md-nav__item"> <a href="../../develop/getting-started/package-development/" class="md-nav__link"> Package development </a> </li> <li class="md-nav__item"> <a href="../../develop/getting-started/instance-development/" class="md-nav__link"> Instance development </a> </li> <li class="md-nav__item"> <a href="../../develop/getting-started/debugging/" class="md-nav__link"> Debugging </a> </li> <li class="md-nav__item"> <a href="../../develop/getting-started/code-style/" class="md-nav__link"> Coding style </a> </li> <li class="md-nav__item"> <a href="../../develop/getting-started/virtualenvs/" class="md-nav__link"> Virtual environments </a> </li> <li class="md-nav__item"> <a href="../../develop/getting-started/help/" class="md-nav__link"> Getting help </a> </li> <li class="md-nav__item"> <a href="../../develop/process/" class="md-nav__link"> Development process </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5_3" > <label class="md-nav__link" for="__nav_5_3" id="__nav_5_3_label" tabindex="0"> Best practices </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_5_3_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_5_3"> Best practices </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../develop/best-practices/accessibility/" class="md-nav__link"> Accessibility (a11y) </a> </li> <li class="md-nav__item"> <a href="../../develop/best-practices/commits/" class="md-nav__link"> Commits, PRs & reviews </a> </li> <li class="md-nav__item"> <a href="../../develop/best-practices/css-js/" class="md-nav__link"> CSS/JavaScript </a> </li> <li class="md-nav__item"> <a href="../../develop/best-practices/react/" class="md-nav__link"> React </a> </li> <li class="md-nav__item"> <a href="../../develop/best-practices/ui/" class="md-nav__link"> User interface </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5_4" > <label class="md-nav__link" for="__nav_5_4" id="__nav_5_4_label" tabindex="0"> Topic guides </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_5_4_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_5_4"> Topic guides </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../develop/topics/resource/" class="md-nav__link"> Building resources </a> </li> <li class="md-nav__item"> <a href="../../develop/topics/service/" class="md-nav__link"> Building services </a> </li> <li class="md-nav__item"> <a href="../../develop/topics/serializers/" class="md-nav__link"> Building serializers </a> </li> <li class="md-nav__item"> <a href="../../develop/topics/uow/" class="md-nav__link"> Grouping atomic operations </a> </li> <li class="md-nav__item"> <a href="../../develop/topics/validation/" class="md-nav__link"> Sanitize input data </a> </li> <li class="md-nav__item"> <a href="../../develop/topics/theming/" class="md-nav__link"> Theming </a> </li> <li class="md-nav__item"> <a href="../../develop/topics/administration_panel/" class="md-nav__link"> Administration panel </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5_5" > <label class="md-nav__link" for="__nav_5_5" id="__nav_5_5_label" tabindex="0"> How-to guides </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_5_5_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_5_5"> How-to guides </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../develop/howtos/i18n/" class="md-nav__link"> Translation (i18n) </a> </li> <li class="md-nav__item"> <a href="../../develop/howtos/custom_fields/" class="md-nav__link"> Create a new custom field </a> </li> <li class="md-nav__item"> <a href="../../develop/howtos/custom_code/" class="md-nav__link"> Create custom code and views </a> </li> <li class="md-nav__item"> <a href="../../develop/howtos/add_javascript/" class="md-nav__link"> Add JavaScript </a> </li> <li class="md-nav__item"> <a href="../../develop/howtos/override_components/" class="md-nav__link"> Override UI React components </a> </li> <li class="md-nav__item"> <a href="../../develop/howtos/search_terms_migration/" class="md-nav__link"> Create search terms mappings </a> </li> <li class="md-nav__item"> <a href="../../develop/howtos/alembic/" class="md-nav__link"> Create a database migration </a> </li> <li class="md-nav__item"> <a href="../../develop/howtos/security-fix/" class="md-nav__link"> Fix a vulnerability </a> </li> <li class="md-nav__item"> <a href="../../develop/howtos/dev_email/" class="md-nav__link"> Test emails locally </a> </li> <li class="md-nav__item"> <a href="../../develop/howtos/route_migration/" class="md-nav__link"> Migrate legacy routes </a> </li> <li class="md-nav__item"> <a href="../../develop/howtos/backup_search_indices/" class="md-nav__link"> Back up search indices </a> </li> <li class="md-nav__item"> <a href="../../develop/howtos/restrict_access/" class="md-nav__link"> Restrict access to pages </a> </li> <li class="md-nav__item"> <a href="../../develop/howtos/notifications/" class="md-nav__link"> Create and configure notifications </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5_6" > <label class="md-nav__link" for="__nav_5_6" id="__nav_5_6_label" tabindex="0"> Architecture </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_5_6_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_5_6"> Architecture </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../develop/architecture/" class="md-nav__link"> Introduction </a> </li> <li class="md-nav__item"> <a href="../../develop/architecture/infrastructure/" class="md-nav__link"> Infrastructure </a> </li> <li class="md-nav__item"> <a href="../../develop/architecture/software/" class="md-nav__link"> Software </a> </li> <li class="md-nav__item"> <a href="../../develop/architecture/runtime/" class="md-nav__link"> Runtime </a> </li> <li class="md-nav__item"> <a href="../../develop/architecture/requests/" class="md-nav__link"> Requests </a> </li> <li class="md-nav__item"> <a href="../../develop/architecture/communities/" class="md-nav__link"> Communities </a> </li> <li class="md-nav__item"> <a href="../../develop/architecture/records/" class="md-nav__link"> Records </a> </li> <li class="md-nav__item"> <a href="../../develop/architecture/event_handling/" class="md-nav__link"> Event handling </a> </li> <li class="md-nav__item"> <a href="../../develop/architecture/notifications/" class="md-nav__link"> Notifications </a> </li> <li class="md-nav__item"> <a href="../../develop/architecture/reading/" class="md-nav__link"> Recommended reading </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5_7" > <label class="md-nav__link" for="__nav_5_7" id="__nav_5_7_label" tabindex="0"> Concepts </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_5_7_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_5_7"> Concepts </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../develop/concepts/concurrency-control/" class="md-nav__link"> Optimistic concurrency control </a> </li> <li class="md-nav__item"> <a href="../../develop/concepts/transactions/" class="md-nav__link"> Database transaction management </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../../deploy/" class="md-nav__link"> Deploy </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_7" > <label class="md-nav__link" for="__nav_7" id="__nav_7_label" tabindex="0"> Reference </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_7_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_7"> Reference </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../reference/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../reference/cli/" class="md-nav__link"> CLI </a> </li> <li class="md-nav__item"> <a href="../../reference/configuration/" class="md-nav__link"> Configuration </a> </li> <li class="md-nav__item"> <a href="../../reference/metadata/" class="md-nav__link"> Metadata </a> </li> <li class="md-nav__item"> <a href="../../reference/metadata/optional_metadata/" class="md-nav__link"> Optional metadata </a> </li> <li class="md-nav__item"> <a href="../../reference/oai_pmh/" class="md-nav__link"> OAI-PMH </a> </li> <li class="md-nav__item"> <a href="../../reference/export_formats/" class="md-nav__link"> Export formats </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_7_8" > <label class="md-nav__link" for="__nav_7_8" id="__nav_7_8_label" tabindex="0"> REST API </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_7_8_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_7_8"> REST API </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../reference/rest_api_index/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../reference/rest_api_quickstart/" class="md-nav__link"> Quickstart </a> </li> <li class="md-nav__item"> <a href="../../reference/rest_api_communities/" class="md-nav__link"> Communities </a> </li> <li class="md-nav__item"> <a href="../../reference/rest_api_drafts_records/" class="md-nav__link"> Drafts and Records </a> </li> <li class="md-nav__item"> <a href="../../reference/rest_api_groups/" class="md-nav__link"> Groups </a> </li> <li class="md-nav__item"> <a href="../../reference/rest_api_members/" class="md-nav__link"> Members </a> </li> <li class="md-nav__item"> <a href="../../reference/rest_api_requests/" class="md-nav__link"> Requests </a> </li> <li class="md-nav__item"> <a href="../../reference/rest_api_users/" class="md-nav__link"> Users </a> </li> <li class="md-nav__item"> <a href="../../reference/rest_api_reviews/" class="md-nav__link"> Reviews </a> </li> <li class="md-nav__item"> <a href="../../reference/rest_api_vocabularies/" class="md-nav__link"> Vocabularies </a> </li> <li class="md-nav__item"> <a href="../../reference/rest_api_names/" class="md-nav__link"> Names </a> </li> <li class="md-nav__item"> <a href="../../reference/rest_api_funders/" class="md-nav__link"> Funders </a> </li> <li class="md-nav__item"> <a href="../../reference/rest_api_awards/" class="md-nav__link"> Awards </a> </li> <li class="md-nav__item"> <a href="../../reference/rest_api_oaipmh_sets/" class="md-nav__link"> OAI-PMH Sets </a> </li> <li class="md-nav__item"> <a href="../../reference/rest_api_statistics/" class="md-nav__link"> Statistics </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_7_9" > <label class="md-nav__link" for="__nav_7_9" id="__nav_7_9_label" tabindex="0"> Custom fields </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_7_9_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_7_9"> Custom fields </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../reference/custom_fields/widgets/" class="md-nav__link"> UI widgets </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_7_10" > <label class="md-nav__link" for="__nav_7_10" id="__nav_7_10_label" tabindex="0"> Administration </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_7_10_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_7_10"> Administration </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../reference/administration_reference/" class="md-nav__link"> Reference </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../../reference/file_storage/" class="md-nav__link"> File storage </a> </li> <li class="md-nav__item"> <a href="../../reference/statistics/" class="md-nav__link"> Usage statistics </a> </li> <li class="md-nav__item"> <a href="../../reference/notifications/" class="md-nav__link"> Notifications </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8" > <label class="md-nav__link" for="__nav_8" id="__nav_8_label" tabindex="0"> Releases </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_8_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8"> Releases </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../releases/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../releases/maintenance-policy/" class="md-nav__link"> Maintenance policy </a> </li> <li class="md-nav__item"> <a href="../../releases/upgrade-policy/" class="md-nav__link"> Upgrade policy </a> </li> <li class="md-nav__item"> <a href="../../releases/security-policy/" class="md-nav__link"> Security policy </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8_5" > <label class="md-nav__link" for="__nav_8_5" id="__nav_8_5_label" tabindex="0"> Version v12.0 LTS </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_8_5_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8_5"> Version v12.0 LTS </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../releases/v12/version-v12.0.0/" class="md-nav__link"> Release Notes v12.0 </a> </li> <li class="md-nav__item"> <a href="../../releases/v12/upgrade-v12.0/" class="md-nav__link"> Upgrade from v11 to v12 </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8_6" > <label class="md-nav__link" for="__nav_8_6" id="__nav_8_6_label" tabindex="0"> Version v11.0 STS </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_8_6_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8_6"> Version v11.0 STS </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../releases/v11/version-v11.0.0/" class="md-nav__link"> Release Notes v11.0 </a> </li> <li class="md-nav__item"> <a href="../../releases/v11/upgrade-v11.0/" class="md-nav__link"> Upgrade from v10 to v11 </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8_7" > <label class="md-nav__link" for="__nav_8_7" id="__nav_8_7_label" tabindex="0"> Version v9.1 LTS </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_8_7_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8_7"> Version v9.1 LTS </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../releases/v9/version-v9.1.0/" class="md-nav__link"> Release Notes v9.1 </a> </li> <li class="md-nav__item"> <a href="../../releases/v9/version-v9.0.0/" class="md-nav__link"> Release Notes v9.0 </a> </li> <li class="md-nav__item"> <a href="../../releases/migrate-docker-images/" class="md-nav__link"> Migrate Docker images </a> </li> <li class="md-nav__item"> <a href="../../releases/v9/migrate-opensearch-v9/" class="md-nav__link"> Migrate v9 to OpenSearch </a> </li> <li class="md-nav__item"> <a href="../../releases/v9/upgrade-v9.0/" class="md-nav__link"> Upgrade from v8 to v9 </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8_8" > <label class="md-nav__link" for="__nav_8_8" id="__nav_8_8_label" tabindex="0"> Legacy Versions </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_8_8_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8_8"> Legacy Versions </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8_8_1" > <label class="md-nav__link" for="__nav_8_8_1" id="__nav_8_8_1_label" tabindex="0"> Version v10.1 </label> <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_8_8_1_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8_8_1"> Version v10.1 </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../releases/v10/version-v10.1.0/" class="md-nav__link"> Release Notes v10.1 </a> </li> <li class="md-nav__item"> <a href="../../releases/v10/version-v10.0.0/" class="md-nav__link"> Release Notes v10.0 </a> </li> <li class="md-nav__item"> <a href="../../releases/v10/upgrade-v10.0/" class="md-nav__link"> Upgrade from v9 to v10 </a> </li> <li class="md-nav__item"> <a href="../../releases/migrate-docker-images/" class="md-nav__link"> Migrate Docker images </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8_8_2" > <label class="md-nav__link" for="__nav_8_8_2" id="__nav_8_8_2_label" tabindex="0"> Version v8.0 </label> <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_8_8_2_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8_8_2"> Version v8.0 </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../releases/v8/version-v8.0.0/" class="md-nav__link"> Release Notes v8.0 </a> </li> <li class="md-nav__item"> <a href="../../releases/v8/upgrade-v8.0/" class="md-nav__link"> Upgrade from v7 to v8 </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8_8_3" > <label class="md-nav__link" for="__nav_8_8_3" id="__nav_8_8_3_label" tabindex="0"> Version v7.0 </label> <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_8_8_3_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8_8_3"> Version v7.0 </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../releases/v7/version-v7.0.0/" class="md-nav__link"> Release Notes v7.0 </a> </li> <li class="md-nav__item"> <a href="../../releases/v7/upgrade-v7.0/" class="md-nav__link"> Upgrade from v6 to v7 </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8_8_4" > <label class="md-nav__link" for="__nav_8_8_4" id="__nav_8_8_4_label" tabindex="0"> Version v6.0.5 </label> <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_8_8_4_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8_8_4"> Version v6.0.5 </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../releases/v6/version-v6.0.5/" class="md-nav__link"> Release Notes v6.0.5 </a> </li> <li class="md-nav__item"> <a href="../../releases/v6/upgrade-v6.0.5/" class="md-nav__link"> Upgrade from v6.0.x to v6.0.5 </a> </li> <li class="md-nav__item"> <a href="../../releases/v6/version-v6.0.0/" class="md-nav__link"> Release Notes v6.0.0 </a> </li> <li class="md-nav__item"> <a href="../../releases/v6/upgrade-v6.0/" class="md-nav__link"> Upgrade from v4 to v6 </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8_8_5" > <label class="md-nav__link" for="__nav_8_8_5" id="__nav_8_8_5_label" tabindex="0"> Version v5.0 </label> <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_8_8_5_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8_8_5"> Version v5.0 </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../releases/v5/version-v5.0.0/" class="md-nav__link"> Release Notes v5.0 </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8_8_6" > <label class="md-nav__link" for="__nav_8_8_6" id="__nav_8_8_6_label" tabindex="0"> Version v4.0 </label> <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_8_8_6_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8_8_6"> Version v4.0 </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../releases/v4/version-v4.0.0/" class="md-nav__link"> Release Notes v4.0 </a> </li> <li class="md-nav__item"> <a href="../../releases/v4/upgrade-v4.0/" class="md-nav__link"> Upgrade from v3 to v4 </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8_8_7" > <label class="md-nav__link" for="__nav_8_8_7" id="__nav_8_8_7_label" tabindex="0"> Version v3.0 </label> <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_8_8_7_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8_8_7"> Version v3.0 </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../releases/v3/version-v3.0.0/" class="md-nav__link"> Release Notes v3.0 </a> </li> <li class="md-nav__item"> <a href="../../releases/v3/upgrade-v3.0/" class="md-nav__link"> Upgrade from v2 to v3 </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8_8_8" > <label class="md-nav__link" for="__nav_8_8_8" id="__nav_8_8_8_label" tabindex="0"> Version v2.0 </label> <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_8_8_8_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8_8_8"> Version v2.0 </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../releases/v2/version-v2.0.0/" class="md-nav__link"> Release Notes v2.0 </a> </li> <li class="md-nav__item"> <a href="../../releases/v2/upgrade-v2.0/" class="md-nav__link"> Upgrade from v1 to v2 </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8_8_9" > <label class="md-nav__link" for="__nav_8_8_9" id="__nav_8_8_9_label" tabindex="0"> Version v1.0 </label> <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_8_8_9_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8_8_9"> Version v1.0 </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../releases/v1/version-v1.0.0/" class="md-nav__link"> Release Notes v1.0 </a> </li> </ul> </nav> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_9" > <label class="md-nav__link" for="__nav_9" id="__nav_9_label" tabindex="0"> Maintainers </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_9_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_9"> Maintainers </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../maintenance/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../maintenance/newcomers/" class="md-nav__link"> Newcomers </a> </li> <li class="md-nav__item"> <a href="../../maintenance/board-workflow/" class="md-nav__link"> Sprintboard workflow </a> </li> <li class="md-nav__item"> <a href="../../maintenance/pr-community-board/" class="md-nav__link"> Community PR board </a> </li> <li class="md-nav__item"> <a href="../../maintenance/release-management/" class="md-nav__link"> Release management </a> </li> <li class="md-nav__item"> <a href="../../maintenance/modules/" class="md-nav__link"> Modules on GitHub </a> </li> <li class="md-nav__item"> <a href="../../maintenance/branch-management/" class="md-nav__link"> Branch management </a> </li> <li class="md-nav__item"> <a href="../../maintenance/demosite/" class="md-nav__link"> Demo site & docs </a> </li> <li class="md-nav__item"> <a href="../../maintenance/docker-images/" class="md-nav__link"> Docker images </a> </li> <li class="md-nav__item"> <a href="../../maintenance/rfcs/" class="md-nav__link"> RFCs </a> </li> <li class="md-nav__item"> <a href="../../maintenance/documentation/" class="md-nav__link"> Writing documentation </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10" > <label class="md-nav__link" for="__nav_10" id="__nav_10_label" tabindex="0"> Onboard & Contribute </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_10"> Onboard & Contribute </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../contribute/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../contribute/onboarding/" class="md-nav__link"> Onboarding </a> </li> <li class="md-nav__item"> <a href="../../contribute/code-of-conduct/" class="md-nav__link"> Code of conduct </a> </li> <li class="md-nav__item"> <a href="../../contribute/copyright-policy/" class="md-nav__link"> Copyright policy </a> </li> <li class="md-nav__item"> <a href="../../contribute/roadmap/" class="md-nav__link"> Roadmap </a> </li> <li class="md-nav__item"> <a href="../../contribute/translators-guide/" class="md-nav__link"> Translators guide </a> </li> </ul> </nav> </li> </ul> </nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" > <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner"> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#local-authentication" class="md-nav__link"> Local Authentication </a> <nav class="md-nav" aria-label="Local Authentication"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#disabling-local-authentication" class="md-nav__link"> Disabling local authentication </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#external-authentication" class="md-nav__link"> External authentication </a> <nav class="md-nav" aria-label="External authentication"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#oauth" class="md-nav__link"> OAuth </a> <nav class="md-nav" aria-label="OAuth"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#orcid" class="md-nav__link"> ORCID </a> </li> <li class="md-nav__item"> <a href="#github" class="md-nav__link"> GITHUB </a> </li> <li class="md-nav__item"> <a href="#keycloak" class="md-nav__link"> Keycloak </a> <nav class="md-nav" aria-label="Keycloak"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#configuration" class="md-nav__link"> Configuration </a> </li> <li class="md-nav__item"> <a href="#tweaking-configuration" class="md-nav__link"> Tweaking configuration </a> </li> <li class="md-nav__item"> <a href="#multiple-keycloak-authentication-providers" class="md-nav__link"> Multiple Keycloak authentication providers </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#openaire-aai" class="md-nav__link"> OpenAIRE AAI </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#login-automatic-redirection" class="md-nav__link"> Login automatic redirection </a> </li> <li class="md-nav__item"> <a href="#user-profile-update" class="md-nav__link"> User profile update </a> </li> <li class="md-nav__item"> <a href="#auto-confirm-user" class="md-nav__link"> Auto-confirm user </a> </li> <li class="md-nav__item"> <a href="#on-the-precedence-mask" class="md-nav__link"> On the precedence mask </a> </li> <li class="md-nav__item"> <a href="#defining-post-logout-url" class="md-nav__link"> Defining post logout url </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#security" class="md-nav__link"> Security </a> </li> <li class="md-nav__item"> <a href="#advanced-integrations" class="md-nav__link"> Advanced integrations </a> <nav class="md-nav" aria-label="Advanced integrations"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#custom-login-page" class="md-nav__link"> Custom login page </a> </li> <li class="md-nav__item"> <a href="#custom-user-registration-form" class="md-nav__link"> Custom user registration form </a> </li> <li class="md-nav__item"> <a href="#custom-user-info" class="md-nav__link"> Custom user info </a> </li> <li class="md-nav__item"> <a href="#new-oauth-plugins" class="md-nav__link"> New OAuth plugins </a> </li> <li class="md-nav__item"> <a href="#allowdeny-user-login" class="md-nav__link"> Allow/deny user login </a> </li> <li class="md-nav__item"> <a href="#saml-integration" class="md-nav__link"> SAML integration </a> <nav class="md-nav" aria-label="SAML integration"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#prerequisites" class="md-nav__link"> Prerequisites </a> </li> <li class="md-nav__item"> <a href="#server-information" class="md-nav__link"> Server information </a> </li> <li class="md-nav__item"> <a href="#configuration_1" class="md-nav__link"> Configuration </a> </li> <li class="md-nav__item"> <a href="#automatically-confirm-users" class="md-nav__link"> Automatically confirm users </a> <nav class="md-nav" aria-label="Automatically confirm users"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#example-configurations-element" class="md-nav__link"> Example configurations element </a> </li> <li class="md-nav__item"> <a href="#troubleshooting-saml-configuration" class="md-nav__link"> Troubleshooting SAML configuration </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#show-the-login-button" class="md-nav__link"> Show the login button </a> </li> <li class="md-nav__item"> <a href="#multiple-saml-authentication-providers" class="md-nav__link"> Multiple SAML authentication providers </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#groups" class="md-nav__link"> Groups </a> <nav class="md-nav" aria-label="Groups"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#add-groups" class="md-nav__link"> Add groups </a> </li> <li class="md-nav__item"> <a href="#assign-groups-on-login" class="md-nav__link"> Assign groups on login </a> </li> </ul> </nav> </li> </ul> </nav> </li> </ul> </nav> </div> </div> </div> <div class="md-content" data-md-component="content"> <article class="md-content__inner md-typeset"> <h1 id="authentication">Authentication<a class="headerlink" href="#authentication" title="Permanent link">¶</a></h1> InvenioRDM supports local authentication only, integration with your institutional authentication system only (e.g. OAuth, SAML, Single Sign-on) or both at the same time. <h2 id="local-authentication">Local Authentication<a class="headerlink" href="#local-authentication" title="Permanent link">¶</a></h2> By default, only the local authentication system is enabled. Users can create a new account using the registration form and activate their account after the email confirmation. These defaults are set in <code>invenio.cfg</code>: <div class="highlight"><pre><code>ACCOUNTS_LOCAL_LOGIN_ENABLED = True # enable local login SECURITY_REGISTERABLE = True # local login: allow users to register SECURITY_RECOVERABLE = True # local login: allow users to reset the password SECURITY_CHANGEABLE = True # local login: allow users to change password SECURITY_CONFIRMABLE = True # require users to confirm their e-mail address </code></pre></div> <h3 id="disabling-local-authentication">Disabling local authentication<a class="headerlink" href="#disabling-local-authentication" title="Permanent link">¶</a></h3> You can disable local authentication by modifying the setting in <code>invenio.cfg</code>: <div class="highlight"><pre><code>ACCOUNTS_LOCAL_LOGIN_ENABLED = False # disable local login </code></pre></div> You typically disable local authentication when you want authentication to be handled by an external provider. As such, when local login is disabled, it is recommended to disable local account registration and password change/recovery: <div class="highlight"><pre><code>SECURITY_REGISTERABLE = False # deny local registration of new users SECURITY_RECOVERABLE = False # deny resetting the local account's password SECURITY_CHANGEABLE = False # deny changing passwords for local accounts </code></pre></div> This way the external provider handles account management. <code>SECURITY_CONFIRMABLE</code> is kept <code>True</code> to check that the user can be reached via a valid email. <div class="admonition warning"> Make sure that your configuration is consistent! While some clearly inconsistent configurations (e.g. having <code>SECURITY_REGISTERABLE=True</code> and at the same time <code>ACCOUNTS_LOCAL_LOGIN_ENABLED=False</code>) will trigger a console warning when running the Invenio webserver, other inconsistent combinations may be silently accepted and ultimately result in unexpected behaviors. </div> <h2 id="external-authentication">External authentication<a class="headerlink" href="#external-authentication" title="Permanent link">¶</a></h2> InvenioRDM supports external authentication out-of-the-box, such as OAuth. SAML authentication can also be experimentally enabled. Note that the redirect url (or authorized) has the format <code>https://<CFG_SITE_URL>/oauth/authorized/<contrib>/</code>, where contrib can be orcid, cern, github, etc. <h3 id="oauth">OAuth<a class="headerlink" href="#oauth" title="Permanent link">¶</a></h3> In addition to local accounts, InvenioRDM offers the possibility to integrate external <a href="https://oauth.net/2/">OAuth 2</a> / <a href="https://openid.net/connect/">OpenID Connect</a> authentication services via the <a href="https://invenio-oauthclient.readthedocs.io/en/latest/">Invenio-OAuthClient</a> module. <h4 id="orcid">ORCID<a class="headerlink" href="#orcid" title="Permanent link">¶</a></h4> After having registered a new client application in the ORCID website and having set as <code>authorized</code> URL <code>https://<CFG_SITE_URL>/oauth/authorized/orcid/</code>, you can enable ORCID login in InvenioRDM by enabling the plugin and configuring key and secret. In your <code>invenio.cfg</code>: <div class="highlight"><pre><code>from invenio_oauthclient.contrib.orcid import REMOTE_APP as ORCID_REMOTE_APP OAUTHCLIENT_REMOTE_APPS = dict( orcid=ORCID_REMOTE_APP, ) ORCID_APP_CREDENTIALS = dict( consumer_key="<my-key>", consumer_secret="<my-secret>", ) </code></pre></div> You can also test ORCID login using the ORCID sandbox environment. See the plugin <a href="https://invenio-oauthclient.readthedocs.io/en/latest/usage.html#module-invenio_oauthclient.contrib.orcid">documentation</a> for more information. <h4 id="github">GITHUB<a class="headerlink" href="#github" title="Permanent link">¶</a></h4> To integrate GitHub authentication into InvenioRDM, follow the steps below: <ul> <li>Register a New GitHub Application by Navigating to GitHub's <a href="https://github.com/settings/applications/new">New OAuth Application page</a> to create a new OAuth application. Provide the necessary details with special attention to the <code>Homepage URL</code> and <code>Authorization callback URL</code>, which should match your InvenioRDM instance's callback URL format:</li> </ul> <div class="highlight"><pre><code>Homepage URL: https://127.0.0.1 Authorization callback URL: https://127.0.0.1/oauth/authorized/github </code></pre></div> Change <code>https://127.0.0.1</code> to <code>SITE_UI_URL</code> in the <code>invenio.cfg</code> file to reflect your actual site URL. After registration, GitHub will provide a <code>Client ID</code> and <code>Client Secret</code>. These credentials are essential for the OAuth integration. <ul> <li>Configure GitHub login in InvenioRDM by enabling the plugin and add the key and secret. In your <code>invenio.cfg</code>:</li> </ul> <div class="highlight"><pre><code>from invenio_oauthclient.contrib.github import REMOTE_APP as GITHUB_REMOTE_APP # Setup Github Authentication # =========================== GITHUB_APP_CREDENTIALS = dict( consumer_key="<my-key>", consumer_secret="<my-secret>", ) OAUTHCLIENT_REMOTE_APPS = dict( github=GITHUB_REMOTE_APP, ) </code></pre></div> If you encounter any issues, or if a <code>302</code> appears in your logs, seek help through this <a href="https://docs.github.com/en/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-authorization-request-errors">resource</a> or join the discussion on <a href="https://discord.gg/8qatqBC">discord</a> for support. <h4 id="keycloak">Keycloak<a class="headerlink" href="#keycloak" title="Permanent link">¶</a></h4> <a href="https://www.keycloak.org/">Keycloak</a> is an open-source solution for identity management that can be used for single sign-on endpoints. <h5 id="configuration">Configuration<a class="headerlink" href="#configuration" title="Permanent link">¶</a></h5> Information required to configure the InvenioRDM instance: <ul> <li>The base URL (including port) of the Keycloak server.</li> <li>Information about the client, as configured in Keycloak:<ul> <li>Its realm.</li> <li>The client ID.</li> <li>The client secret.</li> <li>The target audience of Keycloak's JWTs (probably the same as the client ID).</li> </ul> </li> </ul> <div class="admonition note"> Note The client configuration in Keycloak server must have its access type set to confidential and use the client authenticator mechanism client ID and secret. </div> In your <code>invenio.cfg</code>: <div class="highlight"><pre><code>from invenio_oauthclient.contrib.keycloak import KeycloakSettingsHelper helper = KeycloakSettingsHelper( title="Keycloak", description="Keycloak Authentication Service", base_url="https://myserver.com:4430", realm="my-realm" ) OAUTHCLIENT_KEYCLOAK_REALM_URL = helper.realm_url OAUTHCLIENT_KEYCLOAK_USER_INFO_URL = helper.user_info_url OAUTHCLIENT_KEYCLOAK_VERIFY_EXP = True # whether to verify the expiration date of tokens OAUTHCLIENT_KEYCLOAK_VERIFY_AUD = True # whether to verify the audience tag for tokens OAUTHCLIENT_KEYCLOAK_AUD = "<YOUR.AUDIENCE>" # probably the same as the client ID OAUTHCLIENT_REMOTE_APPS = { "keycloak": helper.remote_app, } KEYCLOAK_APP_CREDENTIALS = { "consumer_key": "<YOUR.CLIENT.ID>", "consumer_secret": "<YOUR.CLIENT.CREDENTIALS.SECRET>", } </code></pre></div> <h5 id="tweaking-configuration">Tweaking configuration<a class="headerlink" href="#tweaking-configuration" title="Permanent link">¶</a></h5> The <code>KeycloakSettingsHelper</code> is only there to make the configuration easier, since the base URL and realm are used several times in the <code>remote_app</code> dictionary. You can change many other settings of the Keycloak configuration in case you need more fine-grained control. Here is what the full configuration looks like: <div class="highlight"><pre><code>>>> helper.remote_app { "title": "Keycloak", "description": "Keycloak Authentication Service", "icon": "", "authorized_handler": "invenio_oauthclient.handlers:authorized_signup_handler", "disconnect_handler": "invenio_oauthclient.contrib.keycloak.handlers:disconnect_handler", "signup_handler": { "info": "invenio_oauthclient.contrib.keycloak.handlers:info_handler", "setup": "invenio_oauthclient.contrib.keycloak.handlers:setup_handler", "view": "invenio_oauthclient.handlers:signup_handler" }, "precedence_mask": {"email": True, "profile": {"username": False, "full_name": False}}, "params": { "base_url": "https://myserver.com:4430", "request_token_params": {"scope": "openid"}, "request_token_url": None, "access_token_url": "https://myserver.com:4430/auth/realms/my-realm/protocol/openid-connect/token", "access_token_method": "POST", "authorize_url": "https://myserver.com:4430/auth/realms/my-realm/protocol/openid-connect/auth", "app_key": "KEYCLOAK_APP_CREDENTIALS" } } >>> helper.realm_url "https://myserver.com:4430/auth/realms/my-realm" >>> helper.user_info_url "https://myserver.com:4430/auth/realms/my-realm/protocol/openid-connect/userinfo" </code></pre></div> <div class="admonition note"> Note The <code>precedence_mask</code> dictates which information about the user (name, email, etc.) provided by authentication server should take precedence over any user input. For more information, see <a href="#on-the-precedence-mask">the related section</a>. </div> You can modify default configuration directly in your <code>invenio.cfg</code>: <div class="highlight"><pre><code>keycloak_remote_app = helper.remote_app # change the title that will be shown in the login button "Login with My institute" keycloak_remote_app["title"] = "My institute" # change the name of the variable holding the credentials keycloak_remote_app["params"]["app_key"] = "OAUTHCLIENT_ANOTHER_NAME_APP_CREDENTIALS" OAUTHCLIENT_ANOTHER_NAME_APP_CREDENTIALS = { "consumer_key": "<YOUR.CLIENT.ID>", "consumer_secret": "<YOUR.CLIENT.CREDENTIALS.SECRET>", } # update the remote apps configuration OAUTHCLIENT_REMOTE_APPS["keycloak"] = keycloak_remote_app </code></pre></div> <h5 id="multiple-keycloak-authentication-providers">Multiple Keycloak authentication providers<a class="headerlink" href="#multiple-keycloak-authentication-providers" title="Permanent link">¶</a></h5> You might have the need to integrate multiple Keycloak authentication providers at the same time, to allow users to log in with one or the other. You can "namespace" each remote application using a different value for the parameter <code>app_key</code>. In your <code>invenio.cfg</code>: <div class="highlight"><pre><code>from invenio_oauthclient.contrib.keycloak import KeycloakSettingsHelper foo = KeycloakSettingsHelper( title="Foo provider", description="Keycloak Authentication foo provider", base_url="https://foo.com:4430", realm="foo-realm", app_key="FOO_KEYCLOAK_APP_CREDENTIALS" ) bar = KeycloakSettingsHelper( title="Bar provider", description="Keycloak Authentication bar provider", base_url="https://bar.com:4430", realm="bar-realm", app_key="BAR_KEYCLOAK_APP_CREDENTIALS" ) OAUTHCLIENT_REMOTE_APPS = { "foo_keycloak": foo.remote_app, "bar_keycloak": bar.remote_app, } OAUTHCLIENT_FOO_KEYCLOAK_REALM_URL = foo.realm_url OAUTHCLIENT_FOO_KEYCLOAK_USER_INFO_URL = foo.user_info_url OAUTHCLIENT_FOO_KEYCLOAK_VERIFY_EXP = True OAUTHCLIENT_FOO_KEYCLOAK_VERIFY_AUD = True OAUTHCLIENT_FOO_KEYCLOAK_AUD = "<FOO.AUDIENCE>" OAUTHCLIENT_BAR_KEYCLOAK_REALM_URL = bar.realm_url OAUTHCLIENT_BAR_KEYCLOAK_USER_INFO_URL = bar.user_info_url OAUTHCLIENT_BAR_KEYCLOAK_VERIFY_EXP = False OAUTHCLIENT_BAR_KEYCLOAK_VERIFY_AUD = True OAUTHCLIENT_BAR_KEYCLOAK_AUD = "<BAR.AUDIENCE>" FOO_KEYCLOAK_APP_CREDENTIALS = { "consumer_key": "<FOO.CLIENT.ID>", "consumer_secret": "<FOO.CLIENT.CREDENTIALS.SECRET>", } BAR_KEYCLOAK_APP_CREDENTIALS = { "consumer_key": "<BAR.CLIENT.ID>", "consumer_secret": "<BAR.CLIENT.CREDENTIALS.SECRET>", } </code></pre></div> <div class="admonition warning"> Naming convention Notice how the <code>app_key</code> param must match with the name of the config <code><APP_KEY>_APP_CREDENTIALS</code>, uppercase, and the name of the apps in the config <code>OAUTHCLIENT_REMOTE_APPS</code> (<code>foo_keycloak</code>, <code>bar_keycloak</code>) must match with the related config vars <code>OAUTHCLIENT_FOO_KEYCLOAK_*</code> and <code>OAUTHCLIENT_BAR_KEYCLOAK_*</code>, uppercase. </div> <h4 id="openaire-aai">OpenAIRE AAI<a class="headerlink" href="#openaire-aai" title="Permanent link">¶</a></h4> Register a new application with OpenAIRE, by sending an email to <a href="mailto:aai@openaire.eu">aai@openaire.eu</a>, with the following information: <ul> <li>Client ID for your application (e.g. <code>my-app</code>).</li> <li>One or more Redirect URIs pointing to <code>https://<host>/oauth/authorized/openaire_aai/</code> ( e.g. <code>https://localhost:5000/oauth/authorized/openaire_aai/</code>).</li> <li>User claim scopes <code>openid profile email orcid</code>.</li> <li>One or more of the OpenID Connect/OAuth2 grant types: Authorization Code, Token Exchange, Device Code.</li> <li>Optionally, you can request to also register an application for the OpenAIRE AAI sandbox instance for testing.</li> </ul> After registering your application, you can enable OpenAIRE login in InvenioRDM by enabling the plugin and configuring the key and secret. In your <code>invenio.cfg</code>: <div class="highlight"><pre><code>from invenio_oauthclient.contrib import openaire_aai OAUTHCLIENT_REMOTE_APPS = dict( openaire_aai=openaire_aai.REMOTE_APP, ) OPENAIRE_APP_CREDENTIALS = dict( consumer_key="changeme", consumer_secret="changeme", ) </code></pre></div> In case you want to use the sandbox environment, use <code>openaire_aai.REMOTE_SANDBOX_APP</code> instead of <code>openaire_aai.REMOTE_APP</code>. <h3 id="login-automatic-redirection">Login automatic redirection<a class="headerlink" href="#login-automatic-redirection" title="Permanent link">¶</a></h3> When local login is disabled and there is exactly one OAuthClient remote app defined, the login page can be skipped and the user can be redirected directly to the external authentication provider. In your <code>invenio.cfg</code>: <div class="highlight"><pre><code>from invenio_oauthclient.views.client import auto_redirect_login ACCOUNTS_LOGIN_VIEW_FUNCTION = auto_redirect_login OAUTHCLIENT_AUTO_REDIRECT_TO_EXTERNAL_LOGIN = True </code></pre></div> This automatic redirection will not work, even if configured as above, if local login is enabled or you have configured multiple remote applications. <h3 id="user-profile-update">User profile update<a class="headerlink" href="#user-profile-update" title="Permanent link">¶</a></h3> You might want to disable the update of the user profile (email, full name, etc.) when only external authentication is enabled. You can set the user profile form as read-only by changing in your <code>invenio.cfg</code>: <div class="highlight"><pre><code>USERPROFILES_READ_ONLY = True </code></pre></div> <h3 id="auto-confirm-user">Auto-confirm user<a class="headerlink" href="#auto-confirm-user" title="Permanent link">¶</a></h3> Introduced in InvenioRDM v11 By default, users who log in using an external authentication provider are <code>confirmed</code> and the e-mail confirmation is not sent anymore. The only exception is the ORCID OAuth plugin: the user e-mail cannot be retrieved by this provider and the user must provide it when registering for the first time. In this case, the registration follows the classic flow, with e-mail confirmation. You can modify this behavior per plugin: <div class="highlight"><pre><code>_keycloak_helper = KeycloakSettingsHelper( title="CERN", description="CERN SSO authentication", ... + signup_options=dict( + auto_confirm=True, + send_register_msg=False, + ), ) </code></pre></div> <h3 id="on-the-precedence-mask">On the precedence mask<a class="headerlink" href="#on-the-precedence-mask" title="Permanent link">¶</a></h3> On first user login after external authentication flow, the user information are fetched from the authentication provider or they might be input by the user via a <a href="#custom-user-registration-form">custom registration form</a>. You can enforce what user information should be taken from the server and cannot be overridden by the user during registration, so that you are sure what information to trust. In your OAuth application, you can fine tune the <code>precedence_mask</code>: <div class="highlight"><pre><code>remote_app["precedence_mask"] = {"email": True, "profile": {"username": False, "full_name": False}} </code></pre></div> Properties marked with <code>True</code> (or omitted) in the precedence mask will be taken from the authentication server user information payload if available, while properties marked with <code>False</code> will be taken from the user input in the registration form. <h3 id="defining-post-logout-url">Defining post logout url<a class="headerlink" href="#defining-post-logout-url" title="Permanent link">¶</a></h3> By default, upon logging out, the application will disconnect you only from itself. However, if you logged in through an external provider, logging out from the application will not automatically log you out from that provider. To address this, you can define a <code>logout_url</code> when setting up the remote apps: <div class="highlight"><pre><code>_keycloak_helper = KeycloakSettingsHelper( title="CERN", description="CERN SSO authentication", ... + logout_url="your_app/logout", ), ) </code></pre></div> After setting the <code>logout_url</code>, it is necessary to include the following configuration variable: <div class="highlight"><pre><code>SECURITY_POST_LOGOUT_VIEW = "/oauth/logout" """Required by invenio-oauthclient to be able to set logout urls for the remote apps.""" </code></pre></div> This will redirect to the appropriate <code>logout_url</code> for each of the enabled remotes in the instance. <h2 id="security">Security<a class="headerlink" href="#security" title="Permanent link">¶</a></h2> For increased security, you should define the following in your <code>invenio.cfg</code>: <div class="highlight"><pre><code>SECURITY_CONFIRMABLE = True # enable e-mail address confirmation for local login SECURITY_TRACKABLE = True # enable tracking of basic user login statistics SECURITY_PASSWORD_SALT = "..put a long random value here.." SECURITY_CONFIRM_SALT = "..put a long random value here.." SECURITY_RESET_SALT = "..put a long random value here.." SECURITY_LOGIN_SALT = "..put a long random value here.." SECURITY_CHANGE_SALT = "..put a long random value here.." SECURITY_REMEMBER_SALT = "..put a long random value here.." </code></pre></div> Additional configuration items for security, sending and customising account registration-related emails, etc. can be found in the <a href="https://flask-security.readthedocs.io/en/latest/configuration.html">documentation for Flask-Security</a>. You can change the default duration (31 days) of the logged in user session (the session cookie expiration). This is particularly useful when configuring InvenioRDM with external authentication only and you want to have the same session duration as the external authentication provider. In your <code>invenio.cfg</code>: <div class="highlight"><pre><code>PERMANENT_SESSION_LIFETIME = timedelta(days=1) </code></pre></div> <h2 id="advanced-integrations">Advanced integrations<a class="headerlink" href="#advanced-integrations" title="Permanent link">¶</a></h2> <h3 id="custom-login-page">Custom login page<a class="headerlink" href="#custom-login-page" title="Permanent link">¶</a></h3> You can customize the login page template to display different information or change its look and feel. Start from an existing template: <ul> <li>If you have local login only, copy the folder <a href="https://github.com/inveniosoftware/invenio-accounts/tree/master/invenio_accounts/templates/semantic-ui">templates/semantic-ui</a> from <code>invenio-accounts</code>.</li> <li>If you have external authentication, copy the folder <a href="https://github.com/inveniosoftware/invenio-oauthclient/tree/master/invenio_oauthclient/templates/semantic-ui">templates/semantic-ui</a> from <code>invenio-oauthclient</code>.</li> </ul> Then, open the <code>templates</code> folder in <code>my-site</code> (your instance) and paste it there. Inside the <code>invenio-accounts</code>/<code>invenio-oauthclient</code> folder, keep only the template file that you want to customize. Edit the Jinja template as you need. For more information, see the guide <a href="../look-and-feel/templates/">style other pages</a>. <h3 id="custom-user-registration-form">Custom user registration form<a class="headerlink" href="#custom-user-registration-form" title="Permanent link">¶</a></h3> Whenever a new user logs in to InvenioRDM with external authentication for the first time, Invenio will create a local account associated with the external account. The local account user information, such as e-mail, username and full name are normally fetched when authenticating and automatically filled in. In case of ORCID login, the user e-mail cannot be retrieved when authenticating and a registration form will be prompted to the user asking to fill in the e-mail. You can customize such behavior and allow users to modify the information coming from the authentication server or require extra user input (e.g. require the user to accept website terms and conditions). The following example configuration creates different registration forms for different external authentication providers. All of them have an extra checkbox for accepting the website's terms and conditions, which is mandatory to complete the registration: <code>my_package/registration_form.py</code>: <div class="highlight"><pre><code>from invenio_oauthclient.utils import create_registrationform from invenio_userprofiles.forms import ProfileForm from wtforms import BooleanField, validators, FormField from werkzeug.local import LocalProxy from flask import current_app, url_for from markupsafe import Markup _security = LocalProxy(lambda: current_app.extensions['security']) def my_registration_form(*args, **kwargs): # create a link to a PDF file containing the terms and conditions # the PDF file is located in the `static/documents` folder. terms_of_use_url = url_for("static", filename=("documents/terms-of-use.pdf")) terms_of_use_text = Markup(f"Accept the <a href='{terms_of_use_url}' target='_blank'>terms and conditions</a>") current_remote_app = kwargs.get("oauth_remote_app") if not current_remote_app: # return default just in case something is wrong return create_registrationform(*args, **kwargs) # optionally, have different registration forms depending on the authentication # provider used by the user to login elif current_remote_app.name.lower() != "orcid": # show this form in case the user logged in with any method but ORCID class DefaultRegistrationForm(_security.confirm_register_form): email = None # remove the email field password = None # remove the password field profile = FormField(ProfileForm, separator=".") recaptcha = None # remove the captcha submit = None # remove submit btn, already defined in the template terms_of_use = BooleanField(terms_of_use_text, [validators.required()]) # add the new field return DefaultRegistrationForm(*args, **kwargs) else: # ORCID does not provide the user e-mail address, it must be input by the user. # the email field comes from `confirm_register_form` upper class. class OrcidRegistrationForm(_security.confirm_register_form): password = None # remove the password field profile = FormField(ProfileForm, separator=".") recaptcha = None # remove the captcha submit = None # remove submit btn, already defined in the template terms_of_use = BooleanField(terms_of_use_text, [validators.required()]) # add the new field return OrcidRegistrationForm(*args, **kwargs) </code></pre></div> <code>invenio.cfg</code>: <div class="highlight"><pre><code>from my_package.registration_form import my_registration_form # use the custom form function OAUTHCLIENT_SIGNUP_FORM = my_registration_form </code></pre></div> <h3 id="custom-user-info">Custom user info<a class="headerlink" href="#custom-user-info" title="Permanent link">¶</a></h3> Introduced in InvenioRDM v11 You can customize how each OAuth plugin will fetch the user information on login, and what fields should be kept or how they should be serialized. You can customize the function that will be called to fetch the user information: <div class="highlight"><pre><code>def info_handler(remote, resp): """Retrieve remote account information. :param remote: The remote application. :param resp: The response of the `authorized` endpoint. :returns: A dictionary with the user information. """ user_info = ... fetch user info ... return custom_info_serializer(user_info) _keycloak_helper = KeycloakSettingsHelper(...) handlers = _keycloak_helper.get_handlers() handlers["signup_handler"]["info"] = custom_info_serializer </code></pre></div> You can customize the function that will be called to serialize the user information: <div class="highlight"><pre><code>def custom_info_serializer(remote, resp, user_info): """Serialize the account info response object. :param remote: The remote application. :param resp: The response of the `authorized` endpoint. :param user_info: The response of the `user info` endpoint. :returns: A dictionary with serialized user information. """ return { "user": { "active": True, "email": user_info["email"], "profile": { "full_name": user_info["name"], "username": user_info["preferred_username"], }, "prefs": { "visibility": "restricted", "email_visibility": "restricted", }, }, "external_id": user_info["upn"], "external_method": remote.name, } _keycloak_helper = KeycloakSettingsHelper(...) handlers = _keycloak_helper.get_handlers() handlers["signup_handler"]["info_serializer"] = custom_info_serializer </code></pre></div> <div class="admonition info"> Mandatory external id When customizing an info endpoint, it is mandatory for a field to provide an external ID. This field must be named <code>external_id</code>. </div> <h3 id="new-oauth-plugins">New OAuth plugins<a class="headerlink" href="#new-oauth-plugins" title="Permanent link">¶</a></h3> If you need to implement your own OAuth plugin to enable integration with your OAuth provider, you can take advantage of the available OAuth helper class. You will need anyway to implement some authentication handlers depending on your server authentication workflow. You can take a look to existing implementations in <a href="https://invenio-oauthclient.readthedocs.org">Invenio-OAuthClient</a>. In your <code>invenio.cfg</code>: <div class="highlight"><pre><code>from invenio_oauthclient.contrib.settings import OauthSettingsHelper class MyOAuthSettingsHelper(OAuthSettingsHelper): def __init__(self): super().__init__( title="my plugin", description="a description", base_url="https://myserver.com/", app_key="MY_APP_CREDENTIALS", access_token_url="https://myserver.com/oauth/token", authorize_url="https://myserver.com/oauth/authorize", ) def get_handlers(self): return dict( authorized_handler='invenio_oauthclient.handlers' ':authorized_signup_handler', disconnect_handler=my_disconnect_handler, signup_handler=dict( info=my_account_info, setup=my_account_setup, view='invenio_oauthclient.handlers:signup_handler', ) ) def get_rest_handlers(self): return dict( authorized_handler='invenio_oauthclient.handlers.rest' ':authorized_signup_handler', disconnect_handler=my_disconnect_handler, signup_handler=dict( info=my_account_info, setup=my_account_setup, view='invenio_oauthclient.handlers.rest:signup_handler', ), response_handler='invenio_oauthclient.handlers.rest' ':default_remote_response_handler', authorized_redirect_url='/', disconnect_redirect_url='/', signup_redirect_url='/', error_redirect_url='/' ) ) def my_disconnect_handler(...): ... def my_account_info(...): ... def my_account_setup(...): ... myOAuthHelper = MyOAuthSettingsHelper() OAUTHCLIENT_REMOTE_APPS = dict( myoauth=myOAuthHelper.remote_app, ) MY_APP_CREDENTIALS = dict( consumer_key="<my-key>", consumer_secret="<my-secret>", ) </code></pre></div> <h3 id="allowdeny-user-login">Allow/deny user login<a class="headerlink" href="#allowdeny-user-login" title="Permanent link">¶</a></h3> When using external authentication, you might want to allow or deny user login base on some conditions. For example, you might want to allow only users with e-mails from a specific domain <code>@mydomain.com</code>. To implement such functionality, you will have to change the implementation of the <code>signup_handler.info</code> handler. First, see how to implement a <a href="#new-oauth-plugins">new custom plugin</a>. You can also copy/paste an existing one. Then, implement the <code>signup_handler.info</code> handler as the following (example taken from Keycloak plugin): <div class="highlight"><pre><code>from flask import flash def account_info(remote, resp): user_info = get_user_info(remote, resp) email = user_info["email"].lower() if not email.endswith("@mydomain.com"): flash(_('You are not allowed to login on this website.'), category='danger') abort(401) else: # default implementation ... </code></pre></div> <h3 id="saml-integration">SAML integration<a class="headerlink" href="#saml-integration" title="Permanent link">¶</a></h3> <div class="admonition warning"> Warning While the SAML integration has been tested and should be working following the guide below, it might still need some further updates, in particular to make its configuration easier. </div> SAML stands for Security Assertion Markup Language. It is an XML-based open-standard for transferring identity data between two parties: an identity provider (IdP) and a service provider (SP). <ul> <li>Identity Provider (IDP): Performs authentication and passes the user's identity and authorization level to the service provider.</li> <li>Service Provider (SP): Trusts the identity provider and authorizes the given user to access the requested resource.</li> </ul> <h4 id="prerequisites">Prerequisites<a class="headerlink" href="#prerequisites" title="Permanent link">¶</a></h4> <ul> <li>Make sure you have installed in your system:</li> </ul> <code>libxml2-dev libxmlsec1-dev pkg-config</code> <ul> <li> Make sure you have installed the required Invenio Python module: <div class="highlight"><pre><code>cd my-site pipenv run pip install invenio-saml </code></pre></div> </li> </ul> <h4 id="server-information">Server information<a class="headerlink" href="#server-information" title="Permanent link">¶</a></h4> List of information required to configure the InvenioRDM instance. <ul> <li> SAML requires a x.509 cert to sign and encrypt elements like <code>NameID</code>, <code>Message</code>, <code>Assertion</code>, <code>Metadata</code>. <ul> <li>sp.crt: The public cert of the SP.</li> <li>sp.key: The private key of the SP.</li> </ul> </li> <li> EntityID: Identifier of the IdP entity (must be a URI). </li> <li>SSO(singleSignOnService): URL Target of the IdP where the Authentication Request Message will be sent.</li> <li>SLO(singleLogoutService): URL Location where the <LogoutRequest> from the IdP will be sent (IdP-initiated logout).</li> <li>x509cert: Public X.509 certificate of the IdP.</li> <li> Attributes mapping: IDP in Assertion of the SAML Response provides a dict with all the user data: <ul> <li>For example, given the following SAML response: <div class="highlight"><pre><code>{ "cn": ["Jhon"], "sn": ["Doe"], "mail": ["john.doe@example.com"], "external_id": ["24546786764d"] } </code></pre></div></li> <li>You can create a mapping to the user account fields required by Invenio as the following: <div class="highlight"><pre><code> "mappings": { "email": "mail", "name": "cn", "surname": "sn", "external_id": "external_id", }, </code></pre></div></li> </ul> </li> </ul> <h4 id="configuration_1">Configuration<a class="headerlink" href="#configuration_1" title="Permanent link">¶</a></h4> In your <code>invenio.cfg</code>: <div class="highlight"><pre><code>from invenio_saml.handlers import acs_handler_factory SSO_SAML_DEFAULT_BLUEPRINT_PREFIX = '/saml' """Base URL for the extensions endpoint.""" SSO_SAML_DEFAULT_METADATA_ROUTE = '/metadata/<idp>' """URL route for the metadata request.""" SSO_SAML_DEFAULT_SSO_ROUTE = '/login/<idp>' """URL route for the SP login.""" SSO_SAML_DEFAULT_ACS_ROUTE = '/authorized/<idp>' """URL route to handle the IdP login request.""" SSO_SAML_DEFAULT_SLO_ROUTE = '/slo/<idp>' """URL route for the SP logout.""" SSO_SAML_DEFAULT_SLS_ROUTE = '/sls/<idp>' """URL route to handle the IdP logout request.""" SSO_SAML_IDPS = { # name your authentication provider 'remote_app': { # Basic info "title": "SAML", "description": "SAML Authentication Service", "icon": "", # path to the file i.e. "./saml/sp.crt" 'sp_cert_file': '<./SP_CERT_FILE>', # path to the file i.e. "./saml/sp.key" 'sp_key_file': '<./SP_KEY_FILE>', 'settings': { # If strict is True, then the Python Toolkit will reject unsigned # or unencrypted messages if it expects them to be signed or encrypted. # Also it will reject the messages if the SAML standard is not strictly # followed. Destination, NameId, Conditions ... are validated too. 'strict': True, # Enable debug mode (outputs errors). 'debug': True, # Service Provider Data that we are deploying. 'sp': { # Specifies the constraints on the name identifier to be used to # represent the requested subject. # Take a look on https://github.com/onelogin/python-saml/blob/master/src/onelogin/saml2/constants.py # to see the NameIdFormat that are supported. 'NameIDFormat': 'urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified', }, # Identity Provider Data that we want connected with our SP. 'idp': { # Identifier of the IdP entity (must be a URI) 'entityId': '<IdP_Entity>', # SSO endpoint info of the IdP. (Authentication Request protocol) 'singleSignOnService': { # URL Target of the IdP where the Authentication Request Message # will be sent. 'url': '<SSO_URL>', # SAML protocol binding to be used when returning the <Response> # message. OneLogin Toolkit supports the HTTP-Redirect binding # only for this endpoint. 'binding': 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect' }, # SLO endpoint info of the IdP. 'singleLogoutService': { # URL Location where the <LogoutRequest> from the IdP will be sent (IdP-initiated logout) 'url': '<SLS_URL>', # SAML protocol binding to be used when returning the <Response> # message. OneLogin Toolkit supports the HTTP-Redirect binding # only for this endpoint. 'binding': 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect' }, # Public X.509 certificate of the IdP 'x509cert': '<X.509_oneliner>' }, # Security settings # more on https://github.com/onelogin/python-saml 'security': { 'authnRequestsSigned': False, 'failOnAuthnContextMismatch': False, 'logoutRequestSigned': False, 'logoutResponseSigned': False, 'metadataCacheDuration': None, 'metadataValidUntil': None, 'nameIdEncrypted': False, 'requestedAuthnContext': False, 'requestedAuthnContextComparison': 'exact', 'signMetadata': False, 'signatureAlgorithm': 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256', 'wantAssertionsEncrypted': False, 'wantAssertionsSigned': False, 'wantAttributeStatement': False, 'wantMessagesSigned': False, 'wantNameId': True, 'wantNameIdEncrypted': False, 'digestAlgorithm': 'http://www.w3.org/2001/04/xmlenc#sha256' }, }, # Account Mapping "mappings": { "email": "<attribute_email>", "name": "<attribute_name>", "surname": "<attribute_surname>", "external_id": "<attribute_external_id>", }, # Inject your remote_app to handler # Note: keep in mind the string should match # given name for authentication provider 'acs_handler': acs_handler_factory('remote_app'), # Automatically set `confirmed_at` for users upon # registration, when using the default `acs_handler` 'auto_confirm': False, } } </code></pre></div> <h4 id="automatically-confirm-users">Automatically confirm users<a class="headerlink" href="#automatically-confirm-users" title="Permanent link">¶</a></h4> When using the default <code>acs_handler</code> for an authentication provider, users can be automatically confirmed upon registration by setting the <code>auto_confirm</code> attribute of a provider to <code>True</code> (default is <code>False</code>). This will set the <code>confirmed_at</code> attribute of the user to the current time. This can be done on a per provider basis, as not every provider may receive the same level of trust for a repository. The <code>mappings</code> attributes are critical to getting your SAML configuration working correctly. The values for <code><attibute_email></code>, <code><attribute_name></code>, <code><attribute_surname></code> and <code><attribute_external_id></code> are set in the <code>urn:oid</code> notation. If you are coming from an institution that uses the eduPerson as what is returned from your IdP you'll need to make those names into the <code>urn:oid</code> form. Example mapping of <code>urn:oasis</code> to <code>urn:oid</code> like those provided at <a href="https://spaces.ais.ucla.edu/display/iamucladocs/Mapping+of+URN+Attributes+and+OID+Attributes">University of California</a> administrative information systems website may provide a clue to how your institution needs to map the SAML response from the IdP. NOTE: In the above example the <code><idp></code> values do not need to be replaced. Invenio-RDM will map those internally. <h5 id="example-configurations-element">Example configurations element<a class="headerlink" href="#example-configurations-element" title="Permanent link">¶</a></h5> Here's an example mapping eduPerson elements to <code>urn:oid</code>. If you're not sure of your institutions mappings reach out to your IdP and search for "<code>eduPerson to</code>urn:oid`" and see what others have documented. <div class="highlight"><pre><code> "mappings": { # email mapped form eduPerson.mail "email": "urn:oid:0.9.2342.19200300.100.1.3", # name mapped from eduPerson.givenName "name": "urn:oid:2.5.4.42", # surname maps to eduPerson.sn "surname": "urn:oid:2.5.4.4", # external_id mapps to eduPerson.eduPersonPrincipalName # (e.g. jane.doe@example.edu) "external_id": "urn:oid:1.3.6.1.4.1.5923.1.1.1.6", }, </code></pre></div> <h5 id="troubleshooting-saml-configuration">Troubleshooting SAML configuration<a class="headerlink" href="#troubleshooting-saml-configuration" title="Permanent link">¶</a></h5> In setting up SAML integration you may run into several scenarios before you "get it right". What are the InvenioRDM SP end points? : In the example above the <code>SSO_SAML_IDPS</code> is a dictionary, the attributes are the names that will be used by InvenioRDM in the SAML interactions. In the example "remote_app" will be an end point, this is probably not ideal, if you have one IdP only you could just name that attribute "ipd", if you have several then a more descriptive attribute name might be warranted. SSO redirects work but Invenio shows 404 on return : This can happen when the IdP is configured in InvenioRDM, the IdP has authorized your SP (the running InvenioRDM instance). If the user isn't actually "logged in" then you may also have trouble in your <code>mappings</code> element. SSO redirects work, InvenioRDM returns a dashboard : It is possible to have SAML/Shibboleth work from some users and not others. This maybe cause by an incorrect <code>mappings</code>. Double check that the values needed by InvenioRDM are getting correct responses, this can be done from checking your system logs for the running InvenioRDM instance. SSO logout fails : This could be as simple as correcting the <code>url</code> value in the <code>Idp</code>, <code>singleLogoutService</code> section. If ancient versions of SAML/Shibboleth did not support "logging out". <h4 id="show-the-login-button">Show the login button<a class="headerlink" href="#show-the-login-button" title="Permanent link">¶</a></h4> The last step is to enable the login template, provided by the SAML module, to display the new button <code>Login with SAML</code>. In your <code>invenio.cfg</code>: <div class="highlight"><pre><code>OAUTHCLIENT_LOGIN_USER_TEMPLATE = "invenio_saml/login_user.html" </code></pre></div> <h4 id="multiple-saml-authentication-providers">Multiple SAML authentication providers<a class="headerlink" href="#multiple-saml-authentication-providers" title="Permanent link">¶</a></h4> You might have the need to integrate multiple SAML authentication providers at the same time, to allow users to log in with one or the other. You can define multiple SAML apps in your <code>invenio.cfg</code>: <div class="highlight"><pre><code>SSO_SAML_IDPS = { # First authentication provider "remote_app": { .... 'settings': { .... }, .... 'acs_handler': acs_handler_factory('remote_app'), 'auto_confirm': True, }, # Second authentication provider "remote_app2": { .... 'settings': { .... }, .... 'acs_handler': acs_handler_factory('remote_app2'), 'auto_confirm': False, }, } </code></pre></div> <h3 id="groups">Groups<a class="headerlink" href="#groups" title="Permanent link">¶</a></h3> A <code>group</code> is a set of users that can be managed in your organization, externally to InvenioRDM. Groups can be useful, for example, to externally manage access and roles of communities' members, without hard coding the list of users in your InvenioRDM instance. Another possible scenario, not yet supported, could be to grant or restrict access to other resources, such as records or files. The support of groups is a feature introduced in the release <a href="https://inveniordm.docs.cern.ch/releases/versions/version-v9.0.0/">v9.0</a>. When integrating groups in your InvenioRDM instance, you will have to: <ol> <li>Import and keep in sync a copy of the groups available in your organization in the InvenioRDM database. This is needed to be able to search for groups when granting/restricting access to resources.</li> <li>When the user signs in, "assign" to the user the list of groups to which (s)he belongs. Read more below.</li> </ol> <div class="admonition notice"> Notice How to import and keep in sync the local copy of groups with your organization' groups is outside the scope of the InvenioRDM documentation and highly depends on your organization's policies, constraints and technologies. </div> <h4 id="add-groups">Add groups<a class="headerlink" href="#add-groups" title="Permanent link">¶</a></h4> In InvenioRDM, groups are simply treated as <code>Roles</code>. To add a group, you create a role: <div class="highlight"><pre><code>from invenio_accounts.proxies import current_datastore current_datastore.create_role(name="it-dep", description="The group containing all users of the IT department.") current_datastore.commit() </code></pre></div> <h4 id="assign-groups-on-login">Assign groups on login<a class="headerlink" href="#assign-groups-on-login" title="Permanent link">¶</a></h4> When the user signs in, you will have to add the user's groups as <code>needs</code> (technically <code>RoleNeed</code>). If an intersection between the <code>RoleNeed</code> (the groups) that the user provides and the <code>RoleNeed</code> that the resource requires exists, then the user has access. With the example above, a user providing a <code>RoleNeed('it-dep')</code> will have access to a resource requiring the <code>RoleNeed('it-dep')</code>. Below, you can find an example of how you can add a <code>RoleNeed</code> on login. <div class="admonition warning"> Use at your own risk The integration of groups is not fully tested yet and the code below is just an example of a possible implementation. </div> Assuming you're implementing a custom <a href="https://inveniordm.docs.cern.ch/customize/authentication/#new-oauth-plugins">OAuth plugin</a>, the fetching of user groups can happen after having fetched user information with the <a href="https://inveniordm.docs.cern.ch/customize/authentication/#allowdeny-user-login"><code>signup_handler.info</code></a> handler. <div class="highlight"><pre><code>def info_handler(remote, resp): ... # existing code user_info = get_user_info(remote, resp) ... # your implementation: fetch groups synchronously roles_or_groups_names = fetch_roles_or_groups_names(remote, user_info) provides = set(UserNeed(current_user.email)) # add groups as Invenio roles to user session for name in roles_or_groups_names: provides.add(RoleNeed(name)) identity.provides |= provides session["<my_external_app_name>_roles"] = provides # end your implementation ... </code></pre></div> The <code>fetch_roles_or_groups_names</code> might retrieve the user groups from the <code>user_info</code> attributes previously fetched or perform a new network request to fetch them from other REST APIs. When groups cannot be retrieved synchronously in the same HTTP request (slow or heavy task), a possible solution could be: <ol> <li>Fetch user groups async in a celery task and store it in the database. The <code>RemoteAccount</code> database table contains a <code>extra_data</code> column which could be used to "cache" user groups.</li> <li>On login, enrich the user session identity <code>provides</code> by reading the list of groups from the database.</li> <li>Refresh the list of user groups of each user when it makes sense in the organization context.</li> </ol> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> </main> <footer class="md-footer"> <nav class="md-footer__inner md-grid" aria-label="Footer" > <a href="../look-and-feel/font/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Change font"> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class="md-footer__title"> Previous <div class="md-ellipsis"> Change font </div> </div> </a> <a href="../emails/" class="md-footer__link md-footer__link--next" aria-label="Next: Sending emails"> <div class="md-footer__title"> Next <div class="md-ellipsis"> Sending emails </div> </div> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-copyright"> <div class="md-copyright__highlight"> Copyright © 2019-2024 CERN, Northwestern University and contributors. </div> Made with <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener"> Material for MkDocs </a> </div> <div class="md-social"> <a href="https://github.com/inveniosoftware" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8M97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> </div> </div> </div> </footer> </div> <div class="md-dialog" data-md-component="dialog"> <div class="md-dialog__inner md-typeset"></div> </div> <script id="__config" type="application/json">{"base": "../..", "features": ["navigation.tabs", "navigation.footer", "content.code.copy"], "search": "../../assets/javascripts/workers/search.6ce7567c.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script> <script src="../../assets/javascripts/bundle.525ec568.min.js"></script> </body> </html>

CINXE.COM

Authentication - Turn-key research data management repository