Flöde vi användning GRP2 för inloggning och underskrift
Ändringshistorik
| Datum | Version | Kommentar |
|---|---|---|
| 2018-11-15 | 1.0 | Publicerad |
| 2019-08-26 | 1.1 | Korrigering av attribut |
| 2020-03-12 | 1.2 | Förtydligande angående medskick av IP-adress |
Inloggning/underskrift via GRP2
BankID eller Net iD access på samma enhet
Vid BankID eller Net iD access på samma enhet. (Informationskanal är samma som säkerhetskanal)
Användarfallet beskriver när en användare via dator/telefon/surfplatta försöka logga in eller skriva under på en e-tjänst via webbläsare och användaren har BankID Säkerhetsprogram eller Net iD access installerat på samma dator/telefon/surfplatta som e-legitmationen.
Flödet beskriver användarfall Webbtjänst.
| 1 | Användaren väljer att logga in/Skriva under på etjänsten | ||
|---|---|---|---|
| 2 | AuthenticateRequest/SignatureRequest(subjectIdentifier, policy, rpDisplayName, transactionId, provider, endUserInfo, requirementAlternatives + (userVisibleData, userNonVisibleData vid SignatureRequest)) | Anrop mot respektive metod | |
| policy | erat tilldelade serviceID | ||
| rpDisplayName | För att kunna hantera olika texter mot användaren i Säkerhetsprogramvaran. Jag legitimerar mig mot: displayname / Jag skriver under hos: rpDisplayName(Används ej av Net iD) | ||
| subjectIdentifier | Används normalt ej då det är metoden. Undantag är om man vet personnumret på den som skall identiferas eller göra underskriften. | ||
| transactionId | En unik identifierar som rekommenderas sättas av kund för spårbarhet. | ||
| provider | bankid/netid | ||
| endUserInfo | *endUserInfo: Skall användas. Sätt användarens IP adress som value med type IP_ADDR | ||
| requirementAlternatives | Används under speciella omständigheter, används sällan. Se separata instruktioner | ||
| userVisibleData | Text som visas vid underskrift. UTF-8 och base64-encoded | ||
| userNonVisibleData | base64-encoded data som ej visas för användaren. Anses inte ha samma juridiska värde. | ||
| 3 | OrderResponse (transactionId, orderRef, AutoStartToken) | Svar från GRP2 | |
| orderRef | Används senare i Collect anropet. Viktigt se till att spara undan det unikt för sessionen. (ej som global parameter) | ||
| AutoStartToken: | Skall användas för att starta Säkerhetsprogram. | ||
| 4 | Starta (launching) | ||
| BankID | Starta säkerhetsapplikation med hjälp av AutoStartToken parametern och en retur adress i URL:en. bankid:///?autostarttoken=[TOKEN]&redirect=[RETURNURL] (Se specifik dokumentation för mer information) | ||
| Net iD | Starta säkerhetsapplikation med hjälp av AutoStartToken parametern och en retur adress i URL:en. netid:///?autostarttoken=[TOKEN]&redirect=[RETURNURL] (Se specifik dokumentation för mer information) | ||
| Användaren anger sin Säkerhetskod i BankID Säkerhetsprogrammet. | |||
| 5 | CollectRequest (policy, transactionId, rpDisplayName, orderRef) | ||
| Polla efter svar. Er applikation skall efter det Säkerhetsprogram har startats, göra en sleep i 3 sekunder för att sedan var 3:e sekund göra en CollectRequest. När det är klart får man status COMPLETE. (efter 30s får man START_FAILED om Säkerhetsprogramvaran ej startat) (Efter 180s blir det time-out och man får EXPIRED_TRANSACTION) | |||
| 6 | CollectResponse (transactionId, progressStatus, userInfo, validationInfo, attributes) | ||
| progressStatus | Status på transaktionen USER_SIGN / COMPLETE(Bara en / orderRef) / OUTSTANDING_TRANSACTION / NO_CLIENT / USER__REQ / STARTED | ||
| UserInfo (subjectIdentifier, subjectIdentifierType, displayName, givenName, sn, ipAddress) | |||
| subjectIdentifier | Personidentitetsbegrepp, oftast personnummer | ||
| subjectIdentifierType | Typ av personidentitetsbegrepp (ssn/email) | ||
| displayName | Fullständigt namn | ||
| givenName | Förnamn | ||
| sn | Efternamn | ||
| ipAddress | Klientens IP-adress | ||
| ValidationInfo (signature, signatureFormat, ocspResponse) | |||
| signature | Vid COMPLETE återfinns bevis på transaktionen skett och bör arkiveras | ||
| SignatureFormat | Signaturformat på signature | ||
| ocspResponse | Base64 OCSP response ifall tillgängligt | ||
| 7 | GrpFault | GrpFault genereras vid eventuella fel. För mer information se GRP2-API. | |
Specialfall: Native App som startar BankID Säkerhetsapp
Har man en egen App som kräver inloggning eller underskrift, så är det troligt att man kan utgå från att BankID Säkerhetsapp är på samma enhet. Detta användarfall följer alltså flödet BankID på samma enhet. Se BankID integrationsguide, hur man startar BankID Säkerhetsapp på olika Mobila operativsystem.
Observera, appen ska prata med kunds etjänst och inte direkt med GRP-API.
BankID, Freja eID+, Net iD på annan enhet
När BankID, Freja eID+, Net iD på annan enhet. (Informationskanal är skild från säkerhetskanal). Detta är den metod som typiskt används för att använda personnummer eller QR-kod vid inloggning när e-legitimationen finns på samma enhet.
Användarfallet beskriver när en användare via dator/surfplatta försöka logga in på en e-tjänst via webbläsare och användaren har Säkerhetsprogramvaran på en annan enhet. QR-kod fungerar bara på BankID och mobila enheter.
Flödet beskriver användarfall Webbtjänst.
| Användaren väljer att logga in/Skriva under på annan enhet på etjänsten | |||
|---|---|---|---|
| 1 | Användaren uppmanas ange personnummer (12-siffror) alternativt scanna QR-koden | ||
| 2 | AuthenticateRequest/SignatureRequest(subjectIdentifier, policy, rpDisplayName, transactionId, provider, endUserInfo, requirementAlternatives + (userVisibleData, userNonVisibleData vid SignatureRequest)) | Anrop mot respektive metod | |
| policy | erat tilldelade serviceID | ||
| rpDisplayName | För att kunna hantera olika texter mot användaren i BankID Säkerhetsprogramvaran. Jag legitimerar mig mot: displayname / Jag skriver under hos: rpDisplayName(Används ej av Net iD) | ||
| subjectIdentifier | Måste skickas som 12-siffror om man inte använder QR-kod | ||
| transactionId | En unik identifierar som rekommenderas sättas av kund för spårbarhet. | ||
| provider | bankid/frejaid/netid | ||
| endUserInfo | endUserInfo: Skall användas. Sätt användarens IP adress som value med type IP_ADDR | ||
| requirementAlternatives | Används under speciella omständigheter, används sällan. Se separata instruktioner | ||
| userVisibleData | Text som visas vid underskrift. UTF-8 och base64-encoded | ||
| userNonVisibleData | base64-encoded data som ej visas för användaren. Anses inte ha samma juridiska värde. | ||
| 3 | OrderResponse (transactionId, orderRef, AutoStartToken) | Svar från GRP2 | |
| orderRef | Används senare i Collect anropet. Viktigt se till att spara undan det unikt för sessionen. (ej som global parameter) | ||
| AutoStartToken: | Skall användas för att starta BankID Säkerhetsprogram. | ||
| 4 | Starta (launching) BankID | ||
| BankID - QR-kod | Starta säkerhetsapplikation med hjälp av AutoStartToken parametern och en retur adress i URL:en. bankid:///?autostarttoken=[TOKEN]&redirect=[RETURNURL] (Se specifik dokumentation för mer information) | ||
| BankID/Freja eID+/Net iD med personnummer | Starta säkerhetsapplikation manuellt på enheten | ||
| 5 | Säkerhetsprogram | ||
| Användaren anger sin Säkerhetskod/fingeravtryck i Säkerhetsprogrammet. | |||
| 6 | CollectRequest (policy, transactionId, rpDisplayName, orderRef) | ||
| Polla efter svar. Er applikation skall efter det Säkerhetsprogram har startats, göra en sleep i 3 sekunder för att sedan var 3:e sekund göra en CollectRequest. När det är klart får man status COMPLETE. (efter 30s får man START_FAILED om man använder autostarttoken med QR-kod) (Efter 180s blir det time-out och man får EXPIRED_TRANSACTION) | |||
| 7 | CollectResponse (transactionId, progressStatus, userInfo, validationInfo, attributes) | ||
| progressStatus | Status på transaktionen USER_SIGN / COMPLETE(Bara en / orderRef) / OUTSTANDING_TRANSACTION / NO_CLIENT / USER__REQ / STARTED | ||
| UserInfo (subjectIdentifier, subjectIdentifierType, displayName, givenName, sn, ipAddress) | |||
| subjectIdentifier | Personidentitetsbegrepp, oftast personnummer | ||
| subjectIdentifierType | Typ av personidentitetsbegrepp (ssn/email) | ||
| displayName | Fullständigt namn | ||
| givenName | Förnamn | ||
| sn | Efternamn | ||
| ipAddress | Klientens IP-adress | ||
| ValidationInfo (signature, signatureFormat, ocspResponse) | |||
| signature | Vid COMPLETE återfinns bevis på att transaktionen skett och bör arkiveras | ||
| SignatureFormat | Signaturformat på signature | ||
| ocspResponse | Base64 OCSP response ifall tillgängligt | ||
| 8 | GrpFault | GrpFault genereras vid eventuella fel. För mer information se GRP2-API. | |
Specialfall när informationskanal inte en dator/telefon/surfplatta
Med BankID/Freja eID+/Net iD på annan enhet kan man säkert identifiera en användare via nya kanaler som exempelvis telefon.
Detta öppnar upp för helt nya möjligheter att genomföra affärer eller erbjuda service till kunder där en säker identifiering är nödvändig. Anslut callcenter systemet till GRP2 och er kundtjänst kan verifiera att det är rätt person man pratar med.
Attribut
Attribut skiljer mellan olika utgivare. Tabellen nedan listar de vanligaste attributen och vilka attribut som förväntas för resp. utgivare
BankID
| Attribut | Beskrivning |
|---|---|
| Subject.SerialNumber | Svenskt personnummer |
| Subject.CommonName | Fullständigt namn |
| Subject.GivenName | Förnamn |
| Subject.Surname | Efternamn |
| Expiredate | Utgångsdatum för certifikat. Format och tillgänglighet varierar för olika utfärdare. |
| notBefore | Datum när certifikatet börjar gälla. och tillgänglighet varierar för olika utfärdare. |
| Security.level | Säkerhetsklassificering, 3 eller 4 |
| Securitylevel.description | Beskrivning av säkerhetsklass. SoftwarePKI SmartcardPKI * MobileTwofactorContract |
| ipAddress | Klientens IP-adress |
| bankidsigneddata.clientinfo.env.ai.type | Enhetstyp Base64 enkodad (ANDROID/IOS/WINDOWS) |
| bankidsigneddata.clientinfo.env.ai.uauth | Använd autentiseringsmetod fp1 - fingeravtryck pw/(blankt) - lösenord/pin |
| (Kompletterande attribut, kan användas för felsökning m.m) | |
| cert.certificatepolicies | Certfikatpolicy |
| cert.issuer.c | Land för certifikatsutgivare |
| cert.issuer.cn | Certifikatutgivare |
| cert.issuer.dn | Certifikatutgivarens DN |
| cert.issuer.o | Utgivande organisation |
| cert.issuer.serialnumber | Serienummer på utgivanda certifikat |
| cert.notafter | Utgångsdatum för certifikat. Format varierar. |
| cert.notbefore | Datum när certifikatet börjar gälla. Format varierar. |
| cert.serialnumber | Certifikatets serienummer, ej att förväxla med personnummer |
| cert.sigalg | Signeringsalgoritm |
| cert.subject.c | Landskod, bör vara SE |
| cert.subject.cn | Fullständigt namn |
| cert.subject.dn | Certifikatets DN |
| cert.subject.givenname | Förnamn |
| cert.subject.oid.2.5.4.41 | Certifikatnamn |
| cert.subject.o | Organisation |
| cert.subject.serialnumber | Svenskt personnummer |
| cert.subject.surname | Efternamn |
| cert.version | Version av certifikat, bör alltid vara 3 |
| bankidsigneddata.clientinfo.env.ai.deviceinfo | Enhetsinformation |
| bankidsigneddata.clientinfo.env.ai.fsib | Reserverad för felsökning |
| bankidsigneddata.clientinfo.env.ai.requirement.condition.type | Certifikatsvillkor |
| bankidsigneddata.clientinfo.env.ai.requirement.condition.value | Värde för certifikatsvillkor |
| bankidsigneddata.clientinfo.env.ai.uhi | Unikt hårdvaruid från BankID RP. |
| bankidsigneddata.clientinfo.env.ai.utb | Typ av e-legitimation |
| bankidsigneddata.clientinfo.funcid | Anropad funktion (Identification/Signing) |
| bankidsigneddata.clientinfo.version | Base64 enkodad version av BankID:s säkerhetsprogramvara |
| bankidsigneddata.srvinfo.displayname | Visat displayName |
| bankidsigneddata.srvinfo.name | Base64 enkodad RP Certifikatnamn |
| bankidsigneddata.srvinfo.nonce | Base64 enkodad nonce |
| Validation.ocsp.response | OCSP svar från spärrkontroll, finns även i validationInfo i GRP-svaret |
Freja eID+
| Attribut | Beskrivning |
|---|---|
| surname | Efternamn |
| name | Förnamn |
| Security.level | Säkerhetsklassificering, 3 eller 4 |
| Securitylevel.description | Beskrivning av säkerhetsklass. SoftwarePKI SmartcardPKI * MobileTwofactorContract |
Övrigt
Cancel och Status
Det finns två funktioner i WSDL-specifikationen som inte är implementerade. De är endast för framtida bruk.
Skicka med IP-adress
Fältet endUserInfo används för att skicka med information om användaren och användarens enhet. För att skicka med IP-adress ser det ut som nedan.
xml
<endUserInfo>
<type>IP_ADDR</type>
<value>192.169.0.1</value> /*example IP-address */
</endUserInfo>
requirementAlternatives
Används för att sätta speciella krav på Säkerhetsprogramvaran, exempel utgivare, fysiskt kort, Mobilt BankID, fingeravtryck, autostarttoken
För ytterligare information se Integrationsguide - BankID
rpDisplayName
-
För användning av BankID rpDisplayName i testmiljön så kan displayname "Test av BankID" och "Funktionstjänster Test" nyttjas. I produktionsmiljön så måste ni till CGI meddela vilket/a rpDisplayName ni skall använda så CGI kan beställa och hantera ett speciellt certifikat till Er. Angivet rpDisplayName måste sen matcha den text ni angivit och finns i certifikatet i CGIs tjänst. Ni måste ange ett av dessa rpDisplayName i Request och sen samma även i Collect anropet. Verifiera gärna att ni kan använda rpDisplayName Funktionstjänster Test så att Svenska tecken fungerar och att rätt teckenkodning används.
-
Freja eID+ rpDisplayname fungerar lite annorlunda än BankID, mer information kommer. Men skicka in cgi_tjanster_test.
-
Net iD access använder sig inte av rpDisplayName, skall således ej skickas in.
DisplayNameRequest
Det är möjligt att lista vilka rpDisplayName som en policy/serviceid har tillgång till i GRP2.
Uppstart av Säkerhetsprogramvara
Vid uppstart av Säkerhetsprogramvaran så bör man ha koll på vilken typ av enhet användaren sitter på och vilken webbläsare. Vissa enheter i kombination med webbläsare kräver andra metoder för att starta. När man använder sig av redirect=[RETURNURL] så är det noga med att man vet att användaren använder startard webbläsaren för det "url-schema(https)" man använder. Annars kommer BankID starta upp fel webbläsare/program. Användaren bör då få ett felmeddelande och inloggningen skall avbrytas, att byta webbläsare/program under inloggning skall inte fungera.
Om Google Chrome används som webbläsare på en IOS-enhet kan redirect url ändras så att den börjar på googlechromes:// istället för https://.
QR-kod
QR-koden skapas av autostarttoken "bankid:///?autostarttoken=[TOKEN]&redirect=[RETURNURL]"
Rekommenderade texter till användaren
BankID har rekommenderade texter som skall användas vid kommunikation med användaren. Dessa är dokumenterade under "User messages" i Integrationsguide - BankID.
Användarna är vana med dessa texter så CGI önskar att dessa följs så långt som möjligt.
Tips & Trix
- Vid användande av QR-kod så måste man generera en ny autostarttoken var 30e sekund om man vill låta användaren ta längre tid på sig utan att få felmeddelande.
- Undvik använda BankID på annan enhet utan QR-kod om möjligt.
Ordlista
- Säkerhetsprogram/Säkerhetsprogramvaran refererar till utgivarens programvara tex BankID Säkerhetsprogram, Net iD Access eller Freja eID.
- netid/Net iD är Net iD access om inget annat anges. Det kan vara tex Efos eller en egen CA, beroende på vad som beställts.