Vettvangur.IcelandAuth is an open-source .Net NuGet library intended to simplify integrating with the island.is authentication service.
island.is's free authentication service allows for authenticating icelandic nationals using digital certificates / Íslykill.
A prior contract with island.is is needed for production use, see https://island.is/innskraningarthjonusta.
This project was developed according to fixes and suggestions from Syndis and influenced in part by the work done here.
- Getting Started
- Configuration
- .Net 5
- Contribution
- License
- Other
Table of contents generated with markdown-toc
Feel free to try out the samples locally configured with our test island.is contract.
Samples listen on port 80. You will also need to configure a dns record mapping:
icelandauth.localhost -> 127.0.0.1
Umbraco samples require the IIS Url Rewrite module
.Net Framework 4.6.1 or .Net Core 2.1.
Some Microsoft.Extensions packages will be installed if missing. They have a light footprint and are used for abstractions made available in .Net Standard.
Grab the NuGet from here
It's best to follow the appropriate sample depending on the framework you target, but these are the basic steps:
Install core library NuGet
Add services.AddIcelandAuth() to Startup
Configure library using appSettings.json
Use in view or controller @inject IcelandAuthService AuthService
Install appropriate Umbraco integration NuGet
Configure library using Web.config
Hook into the ControllerBehavior.Success and Error events to handle authentication events
Note: Umbraco 7 projects configured with dependency injection will need to register an implementation of IcelandAuthService.
Note: Umbraco 8 projects wanting to override the default IcelandAuthService implementation should use Umbraco's RegisterUnique Composition extension method.
Install appropriate Umbraco integration NuGet
Configure library using appSettings
Hook into the ControllerBehavior.Success and Error events to handle authentication events
Add the following to your Startup.cs / Program.cs
services.AddScoped();
To be able to verify the signature returned from island.is you will need to install Íslandsrót in your trusted roots, https://skrar.audkenni.is/skilrikjakedjur/islandsrot/Islandsrot.cer.
The .Net 5 version utilises the CustomRootTrust option to build a chain and comes bundled with the Íslandsrót certificate.
Run the following powershell code with elevated privileges (admin)
Invoke-WebRequest https://skrar.audkenni.is/skilrikjakedjur/islandsrot/Islandsrot.cer -OutFile Islandsrot.cer
Invoke-WebRequest https://skrar.audkenni.is/skilrikjakedjur/islandsrot/Milliskilriki.cer -OutFile Milliskilriki.cer
Import-Certificate .\Islandsrot.cer -CertStoreLocation cert:\localmachine\ca
Import-Certificate .\Milliskilriki.cer -CertStoreLocation cert:\localmachine\ca
$crt = Get-ChildItem -Path cert:\localmachine\ca\9965F6AF08D9BC5E21054AF2B348C19B72D94AE0
Export-Certificate -Cert $crt -FilePath $Env:TEMP\tmpcrt.crt
Import-Certificate $Env:TEMP\tmpcrt.crt -CertStoreLocation cert:\localmachine\root
Remove-Item $env:TEMP\tmpcrt.crt
The certificate Íslandsrót needs to be installed into trusted roots in the server hosts certificate store.
The intermediate certificate (https://skrar.audkenni.is/skilrikjakedjur/islandsrot/Milliskilriki.cer) should be added to Intermediate Certification Authorities.
Installing root certificates is outside the scope of this documentation but a detailed step-by-step can for example be found here.
The sample projects in this repository show how to integrate IcelandAuth with AspNetCore/Umbraco. The Umbraco samples use the core IcelandAuth library and additional umbraco helpers from Vettvangur.IcelandAuth.Umbraco7[/8].
IcelandAuth is configured using appSettings key values, these are commonly stored in Web.config for Asp.Net and appSettings.json for Asp.Net Core projects.
It is also possible to override configured values using the public properties of the IcelandAuthService.
{
"IcelandAuth": {
"ID": "",
"Destination": "",
}
}See a live demo of the Umbraco 8 sample here.
The Umbraco controllers listen for tokens on /umbraco/surface/icelandauth/login.
Code under App_Start shows how to auto-provision users from island.is authentication data.
The following options come from your island.is contract, you can view those values in the island.is control panel.
Ensure SAML response url matches SAML response url destination. Corresponds with "Innskráningarsíða" from the control panel - Required
IcelandAuth:Destination - "http://icelandauth.localhost/icelandauth"IcelandAuth:DestinationSSN - "5208130550"IcelandAuth:ID - "test.icelandauth.vettvangur.is"Possible values include:
- Rafræn skilríki – Digital certificate authentication.
- Rafræn símaskilríki - Digital certificate authentication using a phone.
- Rafræn starfsmannaskilríki – Employee digital certificate authentication.
- Íslykill – Authentication using Íslykill.
- Styrktur Íslykill – 2FA using Íslykill, 2FA delivered via phone or email.
- Styrkt rafræn skilríki – Digital certificate authentication with 2FA via phone/email.
- Styrkt rafræn starfsmannaskilríki – Employee digital certificate authentication with 2FA via phone/email.
Seperate multiple values with comma
IcelandAuth:Authentication - "Rafræn skilríki, Rafræn símaskilríki"If configured and added to the island.is authentication url (the url helper will do this automatically) it will be echoed back in saml response.
It is possible to use this as a form of routing.
F.x. a site with is/en/dk section using the same domain and a single island.is contract id.
If you pick a Guid for each section you can route the user based on the AuthID attribute in Saml response
IcelandAuth:AuthID - "1d5e8fc3-1c02-4d9c-998c-7dd7f0ecc769"Only Guid values are supported.
Check if the users IP matches the one seen at authentication.
This usually fails during development as island.is will see the public ip of the development machine. Meanwhile the development server, if hosted on your internal network, will see your intranet address.
Also unsupported with Cloudflare and will break if user roams during authentication. Not an ideal setting in this day and age.
IcelandAuth:VerifyIPAddress - false // defaultTake care to only enable this option in development!
IcelandAuth:LogSamlResponse - false // defaultThe following settings are used by the umbraco integrations
Can also be configured on a per-login basis using the event callbacks of IcelandAuthController
IcelandAuth:SuccessRedirect - "http://icelandauth.localhost/page?=error=true"
IcelandAuth:ErrorRedirectWhen targetting .Net 5 we make use of X509ChainTrustMode.CustomRootTrust to build the certificate chain.
This simplifies setup by removing the requirement to install certificates locally to a certificate store. They are instead included with the package.
Building now requires latest VS 2019 as Net5 is one of it's targets.
Looking to contribute something? Pull requests are welcome!
- More unit tests
- Documentation in icelandic
- Drop url rewrite module in umbraco samples and instead add route and mvc controller with redirect that keeps post body
Vettvangur.IcelandAuth is licensed under the MIT license. (http://opensource.org/licenses/MIT)
Need help? Something on your mind? Drop us a line at [email protected]