Identifisering

Her finner du dokumentasjon på hva en IPS identifisering er og fungerer, hvordan du bygger opp identifiserings forespørselen og tolker responsen. I tillegg finner du informasjon om de forskjellige instrumentene og id-instillingene du kan bruke.

Merk at eksempelkodene i denne siden er kun ment som illustrasjonseksempeler på kjernemekanismene, og bør "robustifieres"/justeres med feilhåndtering og/eller andre nødvendige tilpasninger før en ev. produksjonssetting.

Hva er en IPS identifisering?

En identifisering i IPS vil returnere informasjon om en sluttbruker hvis sluttbrukeren besitter det aktuelle instrumentet og oppgir nødvendig informasjon. Hva slags type informasjon som returneres tilbake til bruker avhenger av hva brukerstedet ber om, og hva brukerstedets har av rettigheter til å hente.

Eksempler på returinformasjon kan være buypassid, navn og fødselsnummer. Brukerstedet bestemmer selv hva slags instrument(er) som skal brukes ved identifisering.

Identifiseringsinstrumenter

Brukerstedet angir selv hva slags instrument(er) man ønsker sluttbrukeren skal bruke. Dette angis i forespørselen gjennom InstrumentAttribute elementet.

Hvis man f.eks. ønsker å tilby kunden identifisering med Buypass Smartkort og Buypass ID i mobil, anngis dette slik:

BxElement ird = new BxElement("IdentityRequestData");
...
ird.addElement("InstrumentAttribute", new String[] {"name"}, new String[] {"ips:BPSC"});
ird.addElement("InstrumentAttribute", new String[] {"name"}, new String[] {"ips:OTP1"});

Se Gml-IPS-Bx XML Namespace definisjoner for beskrivelse av parametere.

IdPreferences/ID-instillinger

For hvert instrument kan man også angi såkalte IdPreferences (se også Konfigurasjon av autentisering: IdPreferences).

Dette kan sees på som en slags "policy" for hvordan instrumentet skal brukes ved identifisering. Hvis ikke IdPreference angis, vil det bli brukt standard innstillinger for din merchantID for det gitte instrumentet.

Eksempel på eksplisitt angivelse av IdPreferences (sc-userpresent-pki-bid anngir at man ønsker å prioritere bruken av PKI teknologi foran BID teknologi): 

BxElement ird = new BxElement("IdentityRequestData");
...
ird.addElement("InstrumentAttribute", new String[] {"name", "IdPreference"}, new String[] {"ips:BPSC", "sc-userpresent-pki-bid"});
ird.addElement("InstrumentAttribute", new String[] {"name", "IdPreference"}, new String[] {"ips:OTP1", "sc-userpresent-pki-bid"});

Sammensetting av forespørselen

Sammensetting av identifiseringsforespørselen skjer typisk når en sluttbruker ønsker å logge inn/identifisere seg. Ved sammensetting av en identifiseringsforespørsel, er det 4 ting man må ta stilling til:

1. Hvilke instrument(er) som skal brukes
2. Hvilke returverdier du ønsker om sluttbrukeren
3. Hvilket brukergrensesnitt du ønsker å bruke
4. Retur URL (ved re-dirigerte forespørsler)

Instrumenttyper angis som nevnt over i InstrumentAttribute elementet. 

Returverdier angis gjennom ResponseAttribute elementet.

Brukergrensesnitt kode angis gjennom RequestAttribute elementet.

Retur URL angis i ResponseUrl elementet.

Støttebiblioteket vil hjelpe deg med de resterende påkrevde elementene.

Under er et JSP eksempel på en komplett sammensatt forespørsel, hvor man ønsker å bruke Buypass Smartkort for identifisering, og ønsker å angi eksplisitt av man kun aksepterer PKI Smartkort. Vi ønsker å få fødselsnummeret i retur, og vi ønsker også å bruke et IFRAME basert brukergrensesnitt, og må derfor angi dette gjennom RequestAttribute elementet: 

 1:    // build request data
 2:    BxElement ird = new BxElement("IdentityRequestData");
 3:    ird.addElement("RequestId", BxCrypto.generateUid());
 4:    ird.addElement("ResponseUrl", 
 5:		"http://mysite.com/processlogin.do");
 6:    
 7:    // add additional instrument preferences
 8:    ird.addElement("InstrumentAttribute", new String[] 
 9:    		{"name", "IdPreference"}, new String[] 
10:		{"ips:BPSC", "sc-userpresent-pkionly"});
11:
12:    // add additonal response attributes
13:    ird.addElement("ResponseAttribute", new String[] 
14:		{"name"}, new String[] {"ips:SSN"});
15:
16:	// choose framebased GUI (not default)
17:    ird.addElement("RequestAttribute",    new String[] 
18:		{"name"}, new String[] {"ips:GUI"});
19:    ird.getElement("RequestAttribute", 0).setValue("WIPSGUI");
20:    
21:    // build request, add missing header data, sign and encrypt
22:    BxRequest req = new BxRequest("IdentityRequest", ird, true);
23:
24:	// get the form data that we're gonna transmitt to the IPS
25:    String pse = req.getPSE(); // the request
26:    String e = req.getE();     // the session key
27:    
28:    // put the request object on session. we need this to be
29:    // able to parse the request context specific response
30:    request.getSession().setAttribute("_idrequest_", req);

Ved å bruke en statisk streng ("_idrequest_") innenfor sesjonen (session-scope), er man også sikker på at det kun er den til enhver tid sist gjeldende identifiseringsforespørselen som er gyldig, siden hver request-response instans er unik og binder hverandre sammen gjennom en forespørselsspesifikk nøkkel.

Relevante elementer å forholde seg til ifm sammensetting av en identifiseringsforespørsel er:

• IdentityRequest
• IdentityRequestData
• ResponseURL
• InstrumentAttribute
• RequestAttribute
• ResponseAttribute

Under er et enklere eksempel som kun bruker prekonfigurerte innstillinger for den gitte merchantID'en (prekonfigurert instrument, IdPreferences, returverdier og GUI kode).

Da spesifiseres i praksis kun retur URL: 

 1:    // build request data
 2:    BxElement ird = new BxElement("IdentityRequestData");
 3:    ird.addElement("RequestId", BxCrypto.generateUid());
 4:    ird.addElement("ResponseUrl", 
 5:		"http://mysite.com/processlogin.do");
 6:    
 7:    // build request, add missing header data, sign and encrypt
 8:    BxRequest req = new BxRequest("IdentityRequest", ird, true);
 9:
10:	// get the form data that we're gonna transmitt to the IPS
11:    String pse = req.getPSE(); // the request
12:    String e = req.getE();     // the session key
13:    
14:    // put the request object on session. we need this to be
15:    // able to parse the request context specific response
16:    request.getSession().setAttribute("_idrequest_", req);

Redirigering/sending av forespørselen til IPS

Når identifiseringsforespørselen er satt sammen og klar, må den sendes til IPS. Dette gjøres ved å sende PSE og E parameteren til IPS, sammen med OP (operasjonstype) og M (merchantID) parameterene i en HTML form. 

HTML form'en returneres tilbake til nettleseren, og sendes automatisk til IPS (v.h.a. "auto-submit"/submit på body-on-load eventen). Under er et eksempel på en side som gjør dette basert på "pse" og "e" variablene fra det første eksempelet over (linje 25 og 26).

I eksempelet under er merchantID=32: 

<html>
  <body 
    onload="javascript:document.getElementById('idForm').submit()">
    <form id="idForm" 
      action="https://secure.test4.buypass.no/wips/service" 
      method="POST">
        <input type="hidden" name="PSE" value="<%=pse%>">
        <input type="hidden" name="E" value="<%=e%>">
        <input type="hidden" name="M" value="32">
        <input type="hidden" name="op" value="BxID">
    </form>
  </body>
</html>

Javascript støtte er påkrevd i nettleseren for bruk av IPS.

Mottak og tolking av responsen

Returdataene fra identifiseringen "kommer tilbake" til brukerstedet på samme måte som de ble sendt til IPS. Det vil si at IPS vil returnere identifiseringsdataene tilbake til nettleseren, som vil bli POST'et tilbake til brukerstedet på anngitt adresse (ResponseUrl).

Parameteren som inneholder returverdiene heter PE. Denne leses typisk ved å kalle 

String pe = request.getParameter("PE");

i en JSP fil. For å kunne dekryptere denne, må det korresponderende BxRequest objektet være tilgjengelig. I eksempelene over, ble dette lagt på sesjonsobjektet for å kunne brukes til dekryptering av responsen.

Her er et eksempel på lesing, dekryptering og parsing: 

 1:    // parse response data
 2:    BxResponse res = new BxResponse(request.getParameter("PE"));
 3:    res.setRequestContext((BxRequest)request.getSession().
 4: 	  getAttribute("_idrequest_"));
 5:    res.parse();
 6:

I koden over har nå BxRequest objektet fra sesjonen blitt tilordnet responsen, og responsen er dekryptert og parset. Neste steg blir å lese ut dataene fra responseobjektene, og tolken responsekoden: 

7:    // get id response object
 8:    BxElement idResponseData = res.
 9:	  getElement("IdentityResponseData");
10:
12:    // get response status
13:    String status = idResponseData.getElement("ResponseCode").
14:		getValue();
15:    String responseMessage = idResponseData.
16:       getElement("ResponseMessage").getValue();
17:    // check status
18:    if(status != null && status.equalsIgnoreCase("ips:SUCCESS")){
19:
20:       // get the id token
21:       BxElement idTokenData = null;
22:       BxElement idToken = idResponseData.getElement("IdToken");
23:       if(idToken != null){
24:          idTokenData = idToken.getElement("IdTokenData");
25:    	     String firstName = idTokenData.getElement("FirstName").
26:		getValue();
27:    	     String lastName = idTokenData.getElement("LastName").
28:		getValue();
29:       }
30:    }