VIGOBAS services

Introduksjon

VIGO-BAS services er et sett med SOAP webservices som primært brukes til å hente data ut og levere data til VIGO-BAS portal, men brukes også for å for eksempel sjekke/generere brukernavn i IDM løsningen.

Løsningen består av syv SOAP webservicer

• Users
• Groups
• Organizations
• Messages
• InternetAccessLevel
• Employments
• FeideMFA

• VIGOBAS services
  • Introduksjon
  • Servicer
    • Users
      • Get
      • GetAll
      • GetForDepartment
      • Employments.svc
        • Get
      • Username.svc
        • CheckSSN
        • CheckUsername
        • CheckDNUsername
        • SearchUsername
        • GetCleanUsername
        • WriteHistory
        • GenerateUsername (Metoder)
          • GenerateUsernameAlt1
          • GenerateUsernameAlt2
          • GenerateUsernameAlt4
          • GenerateUsernameAlt5
          • GenerateUsernameAlt6
    • Groups
    • Organizations
      • Departments.svc
        • Create
        • Get
        • GetAll
        • GetOwnedBy
        • GetDepartmentsAdministeredBy
        • Delete
    • Messages
    • InternetAccessLevel
    • FeideMFA (Feide multifactor authentication)
      • GetADUser
      • GetFeideUser
      • GetQRCode
      • SetMFA
      • GenerateBase32Key
      • GetFeideEncryptedKey
      • GetALevelIDs

Servicer

Users

https://vigobas-services.example.com/Users/profiles.svc

Get

http://VigoBAS-Services.example.com/Users/profiles.svc/get?id=ola.normann

{  
   "Address":"Sivert Tobiesens Gate 4",
   "DisplayName":"Ola Normann",
   "FirstName":"Ola",
   "Id":"ola.normann",
   "LastName":"Normann",
   "PostalCode":"9007",
   "PostalLocation":"TROMSØ",
   "PrimaryDepartment":"BRUNLIEN",
   "PrivateEmail":null,
   "PrivateMobile":"416 81 817",
   "PrivatePhone":null,
   "SocialSecurityNumber":"17128255599",
   "UserId":"00000000-0000-0000-0000-000000000000",
   "Username":"ola.normann",
   "WorkEmail":"ola.normann@vigobas.no",
   "WorkMobile":"999 99 999",
   "WorkPhone":"12 34 56 78"
}

GetAll

Returnerer alle brukere ved alle avdelinger

http://VigoBAS-Services.example.com/Users/profiles.svc/getAll

"Returnerer et array av brukere, for eksempel se GetForDepartment"

GetForDepartment

http://VigoBAS-Services.example.com/Users/profiles.svc/getfordepartment?department=brunlien

[  
   {  
      "Address":null,
      "DisplayName":"Leila Sjøberg",
      "FirstName":"Leila",
      "Id":"leilasjøberg",
      "LastName":"Sjøberg",
      "PostalCode":null,
      "PostalLocation":null,
      "PrimaryDepartment":"BRUNLIEN",
      "PrivateEmail":null,
      "PrivateMobile":null,
      "PrivatePhone":null,
      "SocialSecurityNumber":"87003542123",
      "UserId":"00000000-0000-0000-0000-000000000000",
      "Username":"leilasjøberg",
      "WorkEmail":null,
      "WorkMobile":null,
      "WorkPhone":null
   },
   {  
      "Address":null,
      "DisplayName":"Iqra Helgerud",
      "FirstName":"Iqra",
      "Id":"iqrahelgerud",
      "LastName":"Helgerud",
      "PostalCode":null,
      "PostalLocation":null,
      "PrimaryDepartment":"BRUNLIEN",
      "PrivateEmail":null,
      "PrivateMobile":null,
      "PrivatePhone":null,
      "SocialSecurityNumber":"04437631123",
      "UserId":"00000000-0000-0000-0000-000000000000",
      "Username":"iqrahelgerud",
      "WorkEmail":null,
      "WorkMobile":null,
      "WorkPhone":null
   },
]

Employments.svc

http://vigobas-services.buddy.test.lokal/Users/Employments.svc

Get

http://vigobas-services.buddy.test.lokal/Users/Employments.svc/get?username=ola.normann

[
    {
        "DepartmentDisplayname": "IT-senteret",
        "DepartmentId": "123000",
        "EmploymentId": 007,
        "Leader": null,
        "ResourceId": null,
        "WorkPercentage": 90,
        "WorkTitle": null
    },
    {
        "DepartmentDisplayname": "PO - Lønnsteamet",
        "DepartmentId": "114002",
        "EmploymentId": 007,
        "Leader": null,
        "ResourceId": null,
        "WorkPercentage": 10,
        "WorkTitle": null
    }
]

Username.svc

http://VigoBAS-Services.example.com/Users/Username.svc

CheckSSN

Sjekker om et personnumer har et brukernavn assosiert i Username tabellen og evt. returnerer det.

http://VigoBAS-Services.example.com/Users/Username.svc/checkssn?ssn=1234567890

Eksempel på Svar:

{"Username":"ola.normann"}

CheckUsername

Sjekker om et brukernavn er i bruk ,returnerer True eller False.

http://VigoBAS-Services.example.com/Users/Username.svc/checkusername?username=GjNil

Eksempel på Svar:

{"inUse":false}

CheckDNUsername

Sjekker om brukeren tidligere har et brukernavn basert på DN i agenten. For at dette skal virke krever det at man har en flyt-regel som legger DN i agenten inn i feltet basDN. Og videre flyter dette attributtet til AgentID feltet på Users MA

http://VigoBAS-Services.example.com/Users/Username.svc/checkDNUsername?DN=CS-DN-ID-12345

Eksempel på Svar:

{"username": "olanor"}

SearchUsername

Søker etter brukernavn og returnerer alle som har dette brukernavnet. Man kan søke på tre ulike måter

• start -Søker etter brukernavn som starter på username du har angitt
• end -Søker etter brukernavn som slutter på username du har angitt
• any -Søker etter brukernavn som inneholder username du har angitt

http://VigoBAS-Services.example.com/Users/Username.svc/SearchUsername?username=lano&searchparameter=any

Eksempel på Svar:

{
    "username": "olano",
    "username": "olanor",
    "username": "lanor",
    "username": "lano",
    "username": "lanor3"
}

GetCleanUsername

Søker etter brukernavn i username parameteret og returnerer brukernavn fritt for uønsket innhold (gitt at det er en erstatning for ordet i VigoBAS-Util.Badusernames), samt om det brukernavet tjenesten prøver å foreslå er er i bruk, eller ikke. Er det i bruk må man spørre på et annet brukernavn. Algoritmen støtter ikke å faktisk finne ledig og fritt brukernavn, skulle det bli kollisjon på første brukernavforslag

Søker man etter her knular for å se om det er ledig, vil det først prøve å "vaske" dette brukernavnet fra uheldig sammensetning av brukernavnet og videre sjekke dette. Oppdater eventuelt VigoBAS-Util.Badusernames tabellen om man ønsker å ha flere mulige treff og erstatning for disse

http://VigoBAS-Services.example.com/Users/Username.svc/GetCleanUsername?username=knular

Eksempel på Svar:

{
    "username": "kunlar",
    "inuse": "true",
    "badusername" : "false"
}

WriteHistory

Skriver brukernavn til historikk tabellen

http://VigoBAS-Services.example.com/Users/Username.svc/writehistory?username=pablo.escobar&ssn=17128245617

Returnerer status for success eller evt. feil

{"Status":"Success"}

GenerateUsername (Metoder)

Generate Username metodene er litt større kall som tar seg av hele løpet rundt det å generere brukernavn. GenerateUsernameAltX metodene tar seg alt av sjekker ,vasking og skriving til historikktabell(Feide-krav) før den returnerer et ferdig vasket og sjekket brukernavn

• Sjekker om personnummer allerede har et personnumer knyttet til seg og evt. returnerer det.
• Sjekker at brukernavnet som blir generert er unikt.
• Evt. Genererer brukernavn på alternativ algoritme
• Skriver til Username tabellen for historikk

Fleste nettlesere og rammeverk har automatisk erstatting av ulovlige tegn i URL-en. F.eks mellomrom byttes automatisk med %20. Så paramtetre som f.eks name i eksemplene under kan man sende in "Fornavn Etternavn" helt fint.

GenerateUsernameAlt1

http://VigoBAS-Services.example.com/Users/Username.svc/GetUsernameAlt1?name=Ola%20Normann&ssn=17128244444

{"Username":"ola.normann"}

GenerateUsernameAlt2

http://VigoBAS-Services.example.com/Users/Username.svc/GetUsernameAlt2?name=Ola%20Normann&ssn=17128244444

{"Username":"thola171282"}

GenerateUsernameAlt4

Generer brukernavn "Buddy-style". Metoden lar deg velge antall bokstaver fra fornavn og etternavn og setter så fødselsdato og eventuelt løpenummer til slutt. fName er strengen som kommer først i brukernavnet, lName sist. Så dersom du ønsker etternavndelen først i brukernavnet, settes fName=Etternavn og lName=Fornavn:

http://VigoBAS-Services.example.com/Users/Username.svc/GetUsernameAlt4?fName=Normann&lName=Ola&bDate=1712&ssn=17128244444&gNameCh=2&lNameCh=2

{"Username":"lath1712"}

GenerateUsernameAlt5

Generer brukernavn .

http://VigoBAS-Services.example.com/Users/Username.svc/GetUsernameAlt5?fullName=Ola%20Normann&ssn=17128244444&minNumberOfChars=5&maxNumberOfChars=10&minNumberOflastnameChars=3&useMiddlename=1

{"Username":"olanor"}

GenerateUsernameAlt6

Generer brukernavn prefix + løpenummer. Metoden lar deg sette prefix og start-nummer. Velger neste ledige nr og returnerer prefix og nummer som brukernavn. Ofte omtalt om u-nummer som brukernavn

http://VigoBAS-Services.example.com/Users/Username.svc/GetUsernameAlt?ssn=11223344556&usernameprefix=u&startnumber=100000

{"Username":"u100251"}

Groups

Organizations

http://VigoBAS-Services.example.com/Organizations/Departments.svc

Departments.svc

Create

• POST
• Content-Type: application/json
• http://VigoBAS-Services.example.com/Organizations/Departments.svc?create

Metoden oppretter en Department i tabellen Organizations. Gir ingen returmelding

• string department
• string displayname

{
    "department": "123456789",
    "displayname": "HR avdelingen
}

Get

Metoden henter ut info om en spesifikk Department fra Organizations tabellen

http://VigoBAS-Services.example.com/Organizations/Departments.svc?get=123456789

Returnerer: Name, DisplayName, PostalAddress, ParentOrganization

GetAll

http://VigoBAS-Services.example.com/Organizations/Departments.svc?getall

Returnerer alle department

GetOwnedBy

Metoden henter ut organisajonstre til orgenheter over

http://VigoBAS-Services.example.com/Organizations/Departments.svc?getownedby?123456789

Returnerer en liste med overnforliggende departments

GetDepartmentsAdministeredBy

Metoden henter ut Departments som er underlagt et brukernavn

http://VigoBAS-Services.example.com/Organizations/Departments.svc?GetDepartmentsAdministeredBy=olanor

Delete

Metoden fjerner en department fra organizations tabellen

• Post
• Content-Type: application/json
• http://VigoBAS-Services.example.com/Organizations/Departments.svc

{
    "department": "123456789"
}

Messages

https://vigobas-services.example.com/Messages/email.svc

https://vigobas-services.example.com/Messages/sms.svc

https://vigobas-services.example.com/Messages/sms.svc/registersms

{
  "Recipient": "41691917",
  "Message": "Hello World",
  "SenderName": "VigoBAS",
  "SenderSystem": "Postman"
}

InternetAccessLevel

https://vigobas-services.example.com/Internetaccess/internetaccess.svc

SOAP - Gå til svc adressen for å se kall

FeideMFA (Feide multifactor authentication)

FeideMFA består av et sett med webservices som henter og setter data på personer i et AD LDS (LDAP katalog)

De forskjellige webservicene er:

• GetADUser
• GetFeideUser
• GetQRCode
• SetMFA (Denne utfører alle operasjoner som er nødvendig)
• GenerateBase32Key
• GetFeideEncryptedKey
• GetALevelIDs

GetADUser

Henter data fra AD

attributt	in/out	type
uid	in	string
uid	out	string
Displayname	out	string
mobilephone	out	string

Eksempel http://vigobasservices.example.com/FeideMFA/FeideMFA.svc/GetADUser?uid=USERNAME

GetFeideUser

Henter data fra AD LDS

attributt	in/out	type	Kommentar
uid	in	string
uid	out	string
Alevel	out	string	Feide tjeneste ID-ene
Amethod	out	string	SMS eller TOTP (Feide refererer ofte TOTP som GA)

Eksempel http://vigobasservices.example.com/FeideMFA/FeideMFA.svc/GetFeideUser?uid=USERNAME

GetQRCode

Viser en QR kode for totp applikasjon

attributt	in/out	type	Kommentar
Uid	in	string	Brukernavnet
SecretKey	in	string	Base32 nøkkel 16-tegn
Issuer	in	string	Bruk (a-zA-Z0-9_) uten opphold
	out	image/jpeg

Eksempel http://vigobasservices.example.com/FeideMFA/FeideMFA.svc/GetQRCode?uid=username&SecretKey=ZZCJLSBDCWHFXAM7&issuer=VigoBAS

SetMFA

Setter data i AD LDS for både SMS og TOTP (GA) metode samt returnerer uri til QR-bildet

attributt	in/out	type	Kommentar
uid	in	string
ALevel	in	string	Feide-tjenesteID en eller flere ID-splittet med PIPE-tegn
AMethod	in	string	SMS eller TOTP
Issuer	in	string	Brukernavn på den som aktiverer om to-faktor
qrIssuer	in	string	Teksten i beskrivelsen på QRkoden i retur
IdentificatorType	in	string	Brukernavn til den som aktiverer sterk-autentisering (for logging)
QRCodeuri	out	uri	streng til QR-bilde
Secret	out	string	Base32 nøkkel
UpdateResult	out	boolean	True/False om oppdatering gikk OK eller ikke

Eksempel http://vigobasservices.example.com/FeideMFA/FeideMFA.svc/SetMFA?uid=username&alevel=12345|23456&AMethod=(TOTP or SMS)&issuer=AdminBruker&qrIssuer=FEIDE&IdentificatorType=BankKort

GenerateBase32Key

attributt	in/out	type	kommentar
length	in	integer	Feide krever 16 tegn
Base32EncryptedKey	out	string

Eksempel http://vigobasservices.example.com/FeideMFA/FeideMFA.svc/GenerateBase32Key?length=16

GetFeideEncryptedKey

Denne må defineres i AD LDS for sterk autentisering i iht dokumentasjon fra Feide

attributt	in/out	type	Kommentar
SecretKey	in	string	Benytt base32 string fra GenerateBase32Key
FeideEncryptedKey	out	string

Eksempel http://vigobasservices.example.com/FeideMFA/FeideMFA.svc/GetFeideEncrypted?secretkey=ZZCJLSBDCWHFXAM7

GetALevelIDs

attributt	in/out	type	kommentar
Name	out	string	Navnet på Feidetjenesten
ID	out	string	ID på feidetjenesten
Default	out	bollean	Om den skal være default valgt i dropdown meny

AlevelIDs":[{"Default":true,"ID":"26217","Name":"IT's Learning"}]

Eksempel http://vigobasservices.example.com/FeideMFA/FeideMFA.svc/GetALevelIDs